From 0b961ab7273db3788193e42a764051c470686e93 Mon Sep 17 00:00:00 2001 From: Ariel Yahav Date: Wed, 19 Aug 2026 13:05:20 +0100 Subject: [PATCH 1/2] docs(openapi): describe the schema fields in the spec The Orchestration spec declared its workflow, instance, trigger and stage schemas without saying what any of the fields mean. Add descriptions to v1 and v2, and re-merge the root spec. --- openapi.yaml | 454 ++++++++++++++++++++++++++++++++++++++++++++++++ openapi/v1.yaml | 206 ++++++++++++++++++++++ openapi/v2.yaml | 204 ++++++++++++++++++++++ 3 files changed, 864 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index a3afab3..845b475 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -941,6 +941,7 @@ components: properties: version: type: string + description: Version of the orchestration service Error: type: object required: @@ -949,26 +950,32 @@ components: properties: errorCode: type: string + description: Machine-readable error code identifying the failure enum: - VALIDATION - NOT_FOUND - INTERNAL errorMessage: type: string + description: Human-readable description of the error WorkflowConfig: type: object + description: The stages a workflow runs, in order required: - stages properties: name: type: string + description: Human-readable name for the workflow stages: type: array + description: The stages executed in order when the workflow runs items: type: object additionalProperties: {} Workflow: type: object + description: A workflow definition and the stages it runs required: - config - createdAt @@ -980,11 +987,14 @@ components: createdAt: type: string format: date-time + description: When the workflow was created updatedAt: type: string format: date-time + description: When the workflow was last modified id: type: string + description: Unique identifier of the workflow StageStatus: type: object required: @@ -994,18 +1004,24 @@ components: properties: stage: type: number + description: Zero-based position of the stage within the workflow instanceID: type: string + description: Identifier of the workflow instance this stage belongs to startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running error: type: string + description: Why the stage failed, absent when it succeeded WorkflowInstance: type: object + description: One run of a workflow, tracking its per-stage progress required: - workflowID - id @@ -1015,25 +1031,33 @@ components: properties: workflowID: type: string + description: Identifier of the workflow this run belongs to id: type: string + description: Unique identifier of the run createdAt: type: string format: date-time + description: When the run was started updatedAt: type: string format: date-time + description: When the run was last updated status: type: array + description: Per-stage progress of the run items: $ref: '#/components/schemas/StageStatus' terminated: type: boolean + description: Whether the run has finished, successfully or not terminatedAt: type: string format: date-time + description: When the run finished, absent while it is still running error: type: string + description: Why the run failed, absent when it succeeded workflow: $ref: '#/components/schemas/Workflow' WorkflowInstanceHistoryStage: @@ -1047,27 +1071,36 @@ components: properties: name: type: string + description: Name of the activity this history entry records input: $ref: '#/components/schemas/WorkflowInstanceHistoryStageInput' output: $ref: '#/components/schemas/WorkflowInstanceHistoryStageOutput' error: type: string + description: Why the activity failed, absent when it succeeded terminated: type: boolean + description: Whether the activity has finished startedAt: type: string format: date-time + description: When the activity started terminatedAt: type: string format: date-time + description: When the activity finished, absent while it is still running lastFailure: type: string + description: Error reported by the most recent failed attempt attempt: type: integer + description: How many times the activity has been attempted nextExecution: type: string format: date-time + description: When the next retry is scheduled, absent once the activity + is settled WorkflowInstanceHistory: type: object required: @@ -1078,24 +1111,31 @@ components: properties: name: type: string + description: Name of the stage this history entry records input: $ref: '#/components/schemas/Stage' error: type: string + description: Why the stage failed, absent when it succeeded terminated: type: boolean + description: Whether the stage has finished startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running WorkflowInstanceHistoryList: type: array + description: Per-stage history of a workflow run items: $ref: '#/components/schemas/WorkflowInstanceHistory' WorkflowInstanceHistoryStageList: type: array + description: Per-activity history of a workflow stage items: $ref: '#/components/schemas/WorkflowInstanceHistoryStage' ListWorkflowsResponse: @@ -1105,6 +1145,7 @@ components: items: $ref: '#/components/schemas/Workflow' type: array + description: The workflows defined on this stack required: - data TriggerData: @@ -1115,18 +1156,27 @@ components: properties: event: type: string + description: Type of event that fires this trigger workflowID: type: string + description: Identifier of the workflow to run when the trigger fires version: type: string + description: Version of the trigger definition filter: type: string + description: Expression evaluated against the event. The workflow runs only + when it matches vars: type: object + description: Expressions evaluated against the event to build the workflow's + input variables additionalProperties: true name: type: string + description: Human-readable name for the trigger Trigger: + description: A rule that starts a workflow when a matching event arrives allOf: - $ref: '#/components/schemas/TriggerData' - type: object @@ -1149,17 +1199,23 @@ components: date: type: string format: date-time + description: When the trigger fired workflowInstanceID: type: string + description: Identifier of the run the trigger started, absent when it started + none workflowInstance: $ref: '#/components/schemas/WorkflowInstance' triggerID: type: string + description: Identifier of the trigger that fired event: type: object + description: The event that fired the trigger additionalProperties: true error: type: string + description: Why the trigger failed to start a run, absent when it succeeded ListTriggersOccurrencesResponse: type: object properties: @@ -1167,6 +1223,7 @@ components: items: $ref: '#/components/schemas/TriggerOccurrence' type: array + description: The trigger's occurrences required: - data ListTriggersResponse: @@ -1176,6 +1233,7 @@ components: items: $ref: '#/components/schemas/Trigger' type: array + description: The triggers defined on this stack required: - data CreateWorkflowRequest: @@ -1213,6 +1271,7 @@ components: items: $ref: '#/components/schemas/WorkflowInstance' type: array + description: The runs of this workflow GetWorkflowResponse: type: object required: @@ -1243,24 +1302,32 @@ components: $ref: '#/components/schemas/WorkflowInstanceHistoryStageList' StageSendSourceWallet: type: object + description: Take the funds from a wallet required: - id properties: id: type: string + description: Identifier of the wallet to take funds from balance: type: string + description: Name of the balance within the wallet. Defaults to the main + balance when omitted StageSendDestinationWallet: + description: Send the funds to a wallet $ref: '#/components/schemas/StageSendSourceWallet' StageSendSourceAccount: type: object + description: Take the funds from a ledger account required: - id properties: id: type: string + description: Address of the ledger account to take funds from ledger: type: string + description: Name of the ledger holding the account throughAccount: type: string description: | @@ -1280,14 +1347,17 @@ components: default: false example: true StageSendDestinationAccount: + description: Send the funds to a ledger account $ref: '#/components/schemas/StageSendSourceAccount' StageSendSourcePayment: type: object + description: Take the funds from a payment required: - id properties: id: type: string + description: Identifier of the payment to take funds from ledger: type: string description: | @@ -1312,6 +1382,7 @@ components: default: false StageSendDestinationPayment: type: object + description: Send the funds to a payment required: - psp properties: @@ -1339,6 +1410,7 @@ components: If not specified, the Payments service may use a default account for the connector. StageSendSource: type: object + description: Where a send stage takes the funds from properties: wallet: $ref: '#/components/schemas/StageSendSourceWallet' @@ -1348,6 +1420,7 @@ components: $ref: '#/components/schemas/StageSendSourcePayment' StageSendDestination: type: object + description: Where a send stage puts the funds properties: wallet: $ref: '#/components/schemas/StageSendDestinationWallet' @@ -1366,19 +1439,27 @@ components: $ref: '#/components/schemas/StageSendSource' metadata: type: object + description: Metadata to attach to the resulting transaction additionalProperties: type: string timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) StageDelay: type: object properties: until: type: string format: date-time + description: Wait until this absolute point in time. Mutually exclusive + with duration duration: type: string + description: Wait for this long, expressed as a Go duration such as 10s. + Mutually exclusive with until StageWaitEvent: type: object required: @@ -1386,17 +1467,22 @@ components: properties: event: type: string + description: Type of event the workflow waits for before continuing UpdateAccount: type: object + description: Metadata to set on a ledger account properties: id: type: string + description: Address of the ledger account to update metadata: type: object + description: Metadata to set on the account additionalProperties: type: string ledger: type: string + description: Name of the ledger holding the account required: - id - ledger @@ -1407,6 +1493,7 @@ components: account: $ref: '#/components/schemas/UpdateAccount' Stage: + description: One step of a workflow, whose shape depends on the stage type anyOf: - $ref: '#/components/schemas/StageSend' - $ref: '#/components/schemas/StageDelay' @@ -1417,21 +1504,26 @@ components: properties: connectorID: type: string + description: Identifier of the Stripe connector to transfer through amount: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string + description: Stripe connected account receiving the transfer example: acct_1Gqj58KZcSIg2N2q waitingValidation: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -1442,12 +1534,14 @@ components: example: order_id: '6735' ActivityStripeTransfer: + description: Arguments for the activity that transfers funds through Stripe $ref: '#/components/schemas/StripeTransferRequest' CreateTransferInitiationRequest: type: object properties: connectorID: type: string + description: Identifier of the connector to transfer through provider: type: string description: | @@ -1458,9 +1552,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string @@ -1486,6 +1582,7 @@ components: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -1494,18 +1591,24 @@ components: example: order_id: '6735' ActivityCreateTransferInitiation: + description: Arguments for the activity that initiates a transfer through a + connector $ref: '#/components/schemas/CreateTransferInitiationRequest' ActivityListWallets: type: object + description: Arguments for the activity that lists wallets properties: name: type: string + description: Restrict the listing to wallets with this name ListWalletsResponse: type: object + description: A page of wallets required: - cursor properties: cursor: + description: Paginated cursor wrapping the list of wallets allOf: - $ref: '#/components/schemas/Cursor' - properties: @@ -1536,11 +1639,14 @@ components: description: Metadata associated with the wallet. name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created ledger: type: string + description: Name of the ledger backing this wallet Cursor: type: object required: @@ -1551,35 +1657,46 @@ components: format: int64 minimum: 1 maximum: 1000 + description: Number of items requested per page example: 15 hasMore: type: boolean + description: Whether further pages are available example: false previous: type: string + description: Cursor for the previous page, absent on the first page example: YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol= next: type: string + description: Cursor for the next page, absent on the last page example: '' ActivityGetAccount: type: object + description: Arguments for the activity that reads a ledger account required: - id - ledger properties: id: type: string + description: Address of the ledger account to read ledger: type: string + description: Name of the ledger holding the account ActivityAddAccountMetadata: type: object + description: Arguments for the activity that sets metadata on a ledger account properties: id: type: string + description: Address of the ledger account to update ledger: type: string + description: Name of the ledger holding the account metadata: type: object + description: Metadata to set on the account additionalProperties: type: string required: @@ -1588,44 +1705,56 @@ components: - metadata ActivityCreateTransaction: type: object + description: Arguments for the activity that writes a transaction to a ledger properties: ledger: type: string + description: Name of the ledger to write the transaction to data: $ref: '#/components/schemas/PostTransaction' ActivityRevertTransaction: type: object + description: Arguments for the activity that reverts a ledger transaction required: - id - ledger properties: ledger: type: string + description: Name of the ledger holding the transaction id: type: string + description: Identifier of the transaction to revert ActivityGetPayment: type: object + description: Arguments for the activity that reads a payment required: - id properties: id: type: string + description: Identifier of the payment to read ActivityConfirmHold: type: object + description: Arguments for the activity that confirms a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to confirm ActivityCreditWallet: type: object + description: Arguments for the activity that credits a wallet properties: id: type: string + description: Identifier of the wallet to credit data: $ref: '#/components/schemas/CreditWalletRequest' CreditWalletRequest: type: object + description: A credit to apply to a wallet required: - amount - sources @@ -1640,8 +1769,11 @@ components: description: Metadata associated with the wallet. reference: type: string + description: Optional caller-supplied identifier used to deduplicate the + credit sources: type: array + description: Where the funds come from items: $ref: '#/components/schemas/Subject' balance: @@ -1650,6 +1782,9 @@ components: timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) example: amount: asset: USD/2 @@ -1665,8 +1800,10 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a ledger account identifier: type: string + description: Address of the ledger account WalletSubject: type: object required: @@ -1675,11 +1812,17 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a wallet identifier: type: string + description: Identifier of the wallet balance: type: string + description: Name of the balance within the wallet. Defaults to the main + balance when omitted Subject: + description: The counterparty of a wallet movement, either a ledger account + or another wallet discriminator: propertyName: type mapping: @@ -1690,13 +1833,16 @@ components: - $ref: '#/components/schemas/WalletSubject' ActivityDebitWallet: type: object + description: Arguments for the activity that debits a wallet properties: id: type: string + description: Identifier of the wallet to debit data: $ref: '#/components/schemas/DebitWalletRequest' DebitWalletRequest: type: object + description: A debit to apply to a wallet required: - amount - metadata @@ -1714,10 +1860,13 @@ components: description: Metadata associated with the wallet. description: type: string + description: Human-readable reason for the debit destination: $ref: '#/components/schemas/Subject' balances: type: array + description: Names of the balances to debit from, in order. Defaults to + the main balance when omitted items: type: string description: A targeted balance (use '*' for all) @@ -1734,21 +1883,27 @@ components: pending: true ActivityGetWallet: type: object + description: Arguments for the activity that reads a wallet required: - id properties: id: type: string + description: Identifier of the wallet to read ActivityVoidHold: type: object + description: Arguments for the activity that releases a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to release ActivityGetAccountOutput: + description: Result of the activity that reads a ledger account $ref: '#/components/schemas/AccountResponse' ActivityCreateTransactionOutput: + description: Result of the activity that writes a transaction to a ledger $ref: '#/components/schemas/CreateTransactionResponse' CreateTransactionResponse: properties: @@ -1759,16 +1914,24 @@ components: - data Transaction: type: object + description: A transaction recorded in the ledger, carrying its postings and + metadata properties: timestamp: type: string format: date-time + description: >- + The transaction time: when the transaction is considered to have occurred. + See [bi- temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: The fund movements making up the transaction items: $ref: '#/components/schemas/Posting' reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, + used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/Metadata' @@ -1776,8 +1939,11 @@ components: type: integer format: bigint minimum: 0 + description: Unique sequential identifier for this transaction within the + ledger reverted: type: boolean + description: Indicates if the transaction has been reverted required: - postings - timestamp @@ -1785,10 +1951,12 @@ components: - metadata - reverted ActivityRevertTransactionOutput: + description: Result of the activity that reverts a ledger transaction $ref: '#/components/schemas/RevertTransactionResponse' RevertTransactionResponse: $ref: '#/components/schemas/CreateTransactionResponse' ActivityGetPaymentOutput: + description: Result of the activity that reads a payment $ref: '#/components/schemas/PaymentResponse' PaymentResponse: type: object @@ -1799,6 +1967,7 @@ components: $ref: '#/components/schemas/Payment' Payment: type: object + description: A payment observed or initiated through a connector required: - id - reference @@ -1817,19 +1986,25 @@ components: properties: id: type: string + description: Unique identifier of the payment example: XXX reference: type: string + description: Identifier the payment carries at the provider sourceAccountID: type: string + description: Identifier of the account the funds left destinationAccountID: type: string + description: Identifier of the account the funds reached connectorID: type: string + description: Identifier of the connector that produced the payment provider: $ref: '#/components/schemas/Connector' type: type: string + description: Direction of the payment enum: - PAY-IN - PAYOUT @@ -1841,9 +2016,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount the payment was created with, before any adjustment example: 100 scheme: type: string + description: Payment scheme or rail the payment travelled over enum: - visa - mastercard @@ -1865,21 +2042,26 @@ components: - other asset: type: string + description: Asset the payment is denominated in example: USD createdAt: type: string format: date-time + description: When the payment was created raw: type: object nullable: true + description: The provider's original payload, passed through untouched adjustments: type: array + description: Successive changes to the payment's amount and status items: $ref: '#/components/schemas/PaymentAdjustment' metadata: $ref: '#/components/schemas/PaymentMetadata' Connector: type: string + description: The payment provider behind a connector enum: - STRIPE - DUMMY-PAY @@ -1904,16 +2086,22 @@ components: type: integer format: bigint minimum: 0 + description: Amount carried by this adjustment example: 100 date: type: string format: date-time + description: When the adjustment was recorded raw: type: object + description: The provider's original payload for this adjustment absolute: type: boolean + description: Whether amount replaces the payment's amount rather than adding + to it PaymentStatus: type: string + description: Where a payment stands in its lifecycle enum: - PENDING - ACTIVE @@ -1926,8 +2114,11 @@ components: properties: key: type: string + description: Metadata value carried by the payment nullable: true + description: Arbitrary key/value pairs attached to a payment ActivityDebitWalletOutput: + description: Result of the activity that debits a wallet $ref: '#/components/schemas/DebitWalletResponse' DebitWalletResponse: type: object @@ -1938,6 +2129,8 @@ components: $ref: '#/components/schemas/Hold' Hold: type: object + description: Funds locked by a pending wallet debit, later either confirmed + or voided required: - id - walletID @@ -1958,9 +2151,11 @@ components: type: string description: type: string + description: Human-readable reason the funds were held destination: $ref: '#/components/schemas/Subject' ActivityGetWalletOutput: + description: Result of the activity that reads a wallet $ref: '#/components/schemas/GetWalletResponse' GetWalletResponse: type: object @@ -1971,6 +2166,7 @@ components: $ref: '#/components/schemas/WalletWithBalances' WalletWithBalances: type: object + description: A wallet together with the funds it currently holds required: - name - id @@ -1990,11 +2186,14 @@ components: type: string name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created balances: type: object + description: Aggregated funds held by the wallet, keyed by asset required: - main properties: @@ -2002,6 +2201,7 @@ components: $ref: '#/components/schemas/AssetHolder' ledger: type: string + description: Name of the ledger backing this wallet AssetHolder: type: object required: @@ -2009,11 +2209,13 @@ components: properties: assets: type: object + description: Amounts held, keyed by asset additionalProperties: type: integer format: bigint WorkflowInstanceHistoryStageInput: type: object + description: Arguments an activity was called with, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/ActivityGetAccount' @@ -2043,6 +2245,7 @@ components: $ref: '#/components/schemas/ActivityListWallets' WorkflowInstanceHistoryStageOutput: type: object + description: Result an activity returned, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/ActivityGetAccountOutput' @@ -2060,6 +2263,7 @@ components: $ref: '#/components/schemas/ListWalletsResponse' Monetary: type: object + description: An amount together with the asset it is denominated in required: - asset - amount @@ -2073,18 +2277,25 @@ components: description: The amount of the monetary value. PostTransaction: type: object + description: A transaction to write to a ledger required: - metadata properties: timestamp: type: string format: date-time + description: >- + The transaction time to record, letting you backdate or postdate the transaction. + See [bi- temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: Fund movements to apply. Mutually exclusive with script items: $ref: '#/components/schemas/Posting' script: type: object + description: A Numscript program executed to produce the postings. Mutually + exclusive with postings properties: plain: type: string @@ -2099,11 +2310,14 @@ components: - plain reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, + used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/Metadata' Metadata: type: object + description: Arbitrary key/value pairs attached to the resource additionalProperties: type: string example: @@ -2115,15 +2329,21 @@ components: type: integer format: bigint minimum: 0 + description: Amount to move, as an arbitrary-precision integer expressed + in the asset's smallest unit example: 100 asset: type: string + description: The asset being moved, optionally carrying a scale suffix such + as USD/2 example: COIN destination: type: string + description: Address of the account credited by this posting example: users:002 source: type: string + description: Address of the account debited by this posting example: users:001 required: - amount @@ -2146,15 +2366,19 @@ components: $ref: '#/components/schemas/Trigger' Account: type: object + description: An account in the ledger, identified by its address required: - address - metadata properties: address: type: string + description: The account address, a colon-separated segmented path such + as users:001 example: users:001 metadata: type: object + description: Arbitrary key/value pairs attached to the account properties: {} additionalProperties: type: string @@ -2170,12 +2394,15 @@ components: input: type: integer format: bigint + description: Total amount credited for this asset output: type: integer format: bigint + description: Total amount debited for this asset balance: type: integer format: bigint + description: Net balance, equal to input minus output required: - input - output @@ -2185,6 +2412,7 @@ components: balance: 80 Volumes: type: object + description: Volumes per asset for a single account additionalProperties: $ref: '#/components/schemas/Volume' example: @@ -2203,6 +2431,7 @@ components: properties: version: type: string + description: Version of the orchestration service V2Error: type: object required: @@ -2211,26 +2440,32 @@ components: properties: errorCode: type: string + description: Machine-readable error code identifying the failure enum: - VALIDATION - NOT_FOUND - INTERNAL errorMessage: type: string + description: Human-readable description of the error V2WorkflowConfig: type: object + description: The stages a workflow runs, in order required: - stages properties: name: type: string + description: Human-readable name for the workflow stages: type: array + description: The stages executed in order when the workflow runs items: type: object additionalProperties: {} V2Workflow: type: object + description: A workflow definition and the stages it runs required: - config - createdAt @@ -2242,11 +2477,14 @@ components: createdAt: type: string format: date-time + description: When the workflow was created updatedAt: type: string format: date-time + description: When the workflow was last modified id: type: string + description: Unique identifier of the workflow V2StageStatus: type: object required: @@ -2256,18 +2494,24 @@ components: properties: stage: type: number + description: Zero-based position of the stage within the workflow instanceID: type: string + description: Identifier of the workflow instance this stage belongs to startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running error: type: string + description: Why the stage failed, absent when it succeeded V2WorkflowInstance: type: object + description: One run of a workflow, tracking its per-stage progress required: - workflowID - id @@ -2277,25 +2521,33 @@ components: properties: workflowID: type: string + description: Identifier of the workflow this run belongs to id: type: string + description: Unique identifier of the run createdAt: type: string format: date-time + description: When the run was started updatedAt: type: string format: date-time + description: When the run was last updated status: type: array + description: Per-stage progress of the run items: $ref: '#/components/schemas/V2StageStatus' terminated: type: boolean + description: Whether the run has finished, successfully or not terminatedAt: type: string format: date-time + description: When the run finished, absent while it is still running error: type: string + description: Why the run failed, absent when it succeeded workflow: $ref: '#/components/schemas/V2Workflow' V2WorkflowInstanceHistoryStage: @@ -2309,27 +2561,36 @@ components: properties: name: type: string + description: Name of the activity this history entry records input: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStageInput' output: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStageOutput' error: type: string + description: Why the activity failed, absent when it succeeded terminated: type: boolean + description: Whether the activity has finished startedAt: type: string format: date-time + description: When the activity started terminatedAt: type: string format: date-time + description: When the activity finished, absent while it is still running lastFailure: type: string + description: Error reported by the most recent failed attempt attempt: type: integer + description: How many times the activity has been attempted nextExecution: type: string format: date-time + description: When the next retry is scheduled, absent once the activity + is settled V2WorkflowInstanceHistory: type: object required: @@ -2340,24 +2601,31 @@ components: properties: name: type: string + description: Name of the stage this history entry records input: $ref: '#/components/schemas/V2Stage' error: type: string + description: Why the stage failed, absent when it succeeded terminated: type: boolean + description: Whether the stage has finished startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running V2WorkflowInstanceHistoryList: type: array + description: Per-stage history of a workflow run items: $ref: '#/components/schemas/V2WorkflowInstanceHistory' V2WorkflowInstanceHistoryStageList: type: array + description: Per-activity history of a workflow stage items: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStage' V2ListWorkflowsResponse: @@ -2365,6 +2633,7 @@ components: properties: cursor: type: object + description: Paginated cursor wrapping the list of workflows required: - pageSize - hasMore @@ -2399,18 +2668,27 @@ components: properties: event: type: string + description: Type of event that fires this trigger workflowID: type: string + description: Identifier of the workflow to run when the trigger fires version: type: string + description: Version of the trigger definition filter: type: string + description: Expression evaluated against the event. The workflow runs only + when it matches vars: type: object additionalProperties: true + description: Expressions evaluated against the event to build the workflow's + input variables name: type: string + description: Human-readable name for the trigger V2Trigger: + description: A rule that starts a workflow when a matching event arrives allOf: - $ref: '#/components/schemas/V2TriggerData' - type: object @@ -2433,22 +2711,29 @@ components: date: type: string format: date-time + description: When the trigger fired workflowInstanceID: type: string + description: Identifier of the run the trigger started, absent when it started + none workflowInstance: $ref: '#/components/schemas/V2WorkflowInstance' triggerID: type: string + description: Identifier of the trigger that fired error: type: string + description: Why the trigger failed to start a run, absent when it succeeded event: type: object additionalProperties: true + description: The event that fired the trigger V2ListTriggersOccurrencesResponse: type: object properties: cursor: type: object + description: Paginated cursor wrapping the trigger's occurrences required: - pageSize - hasMore @@ -2480,6 +2765,7 @@ components: properties: cursor: type: object + description: Paginated cursor wrapping the list of triggers required: - pageSize - hasMore @@ -2538,6 +2824,7 @@ components: properties: cursor: type: object + description: Paginated cursor wrapping the list of runs required: - pageSize - hasMore @@ -2594,24 +2881,32 @@ components: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStageList' V2StageSendSourceWallet: type: object + description: Take the funds from a wallet required: - id properties: id: type: string + description: Identifier of the wallet to take funds from balance: type: string + description: Name of the balance within the wallet. Defaults to the main + balance when omitted V2StageSendDestinationWallet: + description: Send the funds to a wallet $ref: '#/components/schemas/V2StageSendSourceWallet' V2StageSendSourceAccount: type: object + description: Take the funds from a ledger account required: - id properties: id: type: string + description: Address of the ledger account to take funds from ledger: type: string + description: Name of the ledger holding the account throughAccount: type: string description: | @@ -2631,14 +2926,17 @@ components: default: false example: true V2StageSendDestinationAccount: + description: Send the funds to a ledger account $ref: '#/components/schemas/V2StageSendSourceAccount' V2StageSendSourcePayment: type: object + description: Take the funds from a payment required: - id properties: id: type: string + description: Identifier of the payment to take funds from ledger: type: string description: | @@ -2663,6 +2961,7 @@ components: default: false V2StageSendDestinationPayment: type: object + description: Send the funds to a payment required: - psp properties: @@ -2690,6 +2989,7 @@ components: If not specified, the Payments service may use a default account for the connector. V2StageSendSource: type: object + description: Where a send stage takes the funds from properties: wallet: $ref: '#/components/schemas/V2StageSendSourceWallet' @@ -2699,6 +2999,7 @@ components: $ref: '#/components/schemas/V2StageSendSourcePayment' V2StageSendDestination: type: object + description: Where a send stage puts the funds properties: wallet: $ref: '#/components/schemas/V2StageSendDestinationWallet' @@ -2717,19 +3018,27 @@ components: $ref: '#/components/schemas/V2StageSendSource' metadata: type: object + description: Metadata to attach to the resulting transaction additionalProperties: type: string timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) V2StageDelay: type: object properties: until: type: string format: date-time + description: Wait until this absolute point in time. Mutually exclusive + with duration duration: type: string + description: Wait for this long, expressed as a Go duration such as 10s. + Mutually exclusive with until V2StageWaitEvent: type: object required: @@ -2737,17 +3046,22 @@ components: properties: event: type: string + description: Type of event the workflow waits for before continuing V2UpdateAccount: type: object + description: Metadata to set on a ledger account properties: id: type: string + description: Address of the ledger account to update metadata: type: object + description: Metadata to set on the account additionalProperties: type: string ledger: type: string + description: Name of the ledger holding the account required: - id - ledger @@ -2758,6 +3072,7 @@ components: account: $ref: '#/components/schemas/V2UpdateAccount' V2Stage: + description: One step of a workflow, whose shape depends on the stage type anyOf: - $ref: '#/components/schemas/V2StageSend' - $ref: '#/components/schemas/V2StageDelay' @@ -2768,21 +3083,26 @@ components: properties: connectorID: type: string + description: Identifier of the Stripe connector to transfer through amount: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string + description: Stripe connected account receiving the transfer example: acct_1Gqj58KZcSIg2N2q waitingValidation: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -2793,12 +3113,14 @@ components: example: order_id: '6735' V2ActivityStripeTransfer: + description: Arguments for the activity that transfers funds through Stripe $ref: '#/components/schemas/V2StripeTransferRequest' V2CreateTransferInitiationRequest: type: object properties: connectorID: type: string + description: Identifier of the connector to transfer through provider: type: string description: | @@ -2809,9 +3131,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string @@ -2837,6 +3161,7 @@ components: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -2845,18 +3170,24 @@ components: example: order_id: '6735' V2ActivityCreateTransferInitiation: + description: Arguments for the activity that initiates a transfer through a + connector $ref: '#/components/schemas/V2CreateTransferInitiationRequest' V2ActivityListWallets: type: object + description: Arguments for the activity that lists wallets properties: name: type: string + description: Restrict the listing to wallets with this name V2ListWalletsResponse: type: object + description: A page of wallets required: - cursor properties: cursor: + description: Paginated cursor wrapping the list of wallets allOf: - $ref: '#/components/schemas/V2Cursor' - properties: @@ -2887,11 +3218,14 @@ components: description: Metadata associated with the wallet. name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created ledger: type: string + description: Name of the ledger backing this wallet V2Cursor: type: object required: @@ -2902,35 +3236,46 @@ components: format: int64 minimum: 1 maximum: 1000 + description: Number of items requested per page example: 15 hasMore: type: boolean + description: Whether further pages are available example: false previous: type: string + description: Cursor for the previous page, absent on the first page example: YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol= next: type: string + description: Cursor for the next page, absent on the last page example: '' V2ActivityGetAccount: type: object + description: Arguments for the activity that reads a ledger account required: - id - ledger properties: id: type: string + description: Address of the ledger account to read ledger: type: string + description: Name of the ledger holding the account V2ActivityAddAccountMetadata: type: object + description: Arguments for the activity that sets metadata on a ledger account properties: id: type: string + description: Address of the ledger account to update ledger: type: string + description: Name of the ledger holding the account metadata: type: object + description: Metadata to set on the account additionalProperties: type: string required: @@ -2939,34 +3284,43 @@ components: - metadata V2ActivityCreateTransaction: type: object + description: Arguments for the activity that writes a transaction to a ledger properties: ledger: type: string + description: Name of the ledger to write the transaction to data: $ref: '#/components/schemas/V2PostTransaction' V2ActivityGetPayment: type: object + description: Arguments for the activity that reads a payment required: - id properties: id: type: string + description: Identifier of the payment to read V2ActivityConfirmHold: type: object + description: Arguments for the activity that confirms a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to confirm V2ActivityCreditWallet: type: object + description: Arguments for the activity that credits a wallet properties: id: type: string + description: Identifier of the wallet to credit data: $ref: '#/components/schemas/V2CreditWalletRequest' V2CreditWalletRequest: type: object + description: A credit to apply to a wallet required: - amount - sources @@ -2981,8 +3335,11 @@ components: description: Metadata associated with the wallet. reference: type: string + description: Optional caller-supplied identifier used to deduplicate the + credit sources: type: array + description: Where the funds come from items: $ref: '#/components/schemas/V2Subject' balance: @@ -2991,6 +3348,9 @@ components: timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) example: amount: asset: USD/2 @@ -3006,8 +3366,10 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a ledger account identifier: type: string + description: Address of the ledger account V2WalletSubject: type: object required: @@ -3016,11 +3378,17 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a wallet identifier: type: string + description: Identifier of the wallet balance: type: string + description: Name of the balance within the wallet. Defaults to the main + balance when omitted V2Subject: + description: The counterparty of a wallet movement, either a ledger account + or another wallet discriminator: propertyName: type mapping: @@ -3031,13 +3399,16 @@ components: - $ref: '#/components/schemas/V2WalletSubject' V2ActivityDebitWallet: type: object + description: Arguments for the activity that debits a wallet properties: id: type: string + description: Identifier of the wallet to debit data: $ref: '#/components/schemas/V2DebitWalletRequest' V2DebitWalletRequest: type: object + description: A debit to apply to a wallet required: - amount - metadata @@ -3055,10 +3426,13 @@ components: description: Metadata associated with the wallet. description: type: string + description: Human-readable reason for the debit destination: $ref: '#/components/schemas/V2Subject' balances: type: array + description: Names of the balances to debit from, in order. Defaults to + the main balance when omitted items: type: string description: A targeted balance (use '*' for all) @@ -3075,26 +3449,33 @@ components: pending: true V2ActivityGetWallet: type: object + description: Arguments for the activity that reads a wallet required: - id properties: id: type: string + description: Identifier of the wallet to read V2ActivityVoidHold: type: object + description: Arguments for the activity that releases a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to release V2ActivityGetAccountOutput: + description: Result of the activity that reads a ledger account $ref: '#/components/schemas/V2AccountResponse' V2ActivityCreateTransactionOutput: + description: Result of the activity that writes a transaction to a ledger $ref: '#/components/schemas/V2CreateTransactionResponse' V2CreateTransactionResponse: properties: data: type: array + description: The transactions that were created items: $ref: '#/components/schemas/V2Transaction' type: object @@ -3106,12 +3487,18 @@ components: timestamp: type: string format: date-time + description: >- + The transaction time: when the transaction is considered to have occurred. + See [bi- temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: The fund movements making up the transaction items: $ref: '#/components/schemas/V2Posting' reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, + used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/V2Metadata' @@ -3119,12 +3506,15 @@ components: type: integer format: bigint minimum: 0 + description: Unique sequential identifier for this transaction within the + ledger required: - postings - timestamp - txid - metadata V2ActivityGetPaymentOutput: + description: Result of the activity that reads a payment $ref: '#/components/schemas/V2PaymentResponse' V2PaymentResponse: type: object @@ -3135,6 +3525,7 @@ components: $ref: '#/components/schemas/V2Payment' V2Payment: type: object + description: A payment observed or initiated through a connector required: - id - reference @@ -3153,19 +3544,25 @@ components: properties: id: type: string + description: Unique identifier of the payment example: XXX reference: type: string + description: Identifier the payment carries at the provider sourceAccountID: type: string + description: Identifier of the account the funds left destinationAccountID: type: string + description: Identifier of the account the funds reached connectorID: type: string + description: Identifier of the connector that produced the payment provider: $ref: '#/components/schemas/V2Connector' type: type: string + description: Direction of the payment enum: - PAY-IN - PAYOUT @@ -3177,9 +3574,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount the payment was created with, before any adjustment example: 100 scheme: type: string + description: Payment scheme or rail the payment travelled over enum: - visa - mastercard @@ -3201,21 +3600,26 @@ components: - other asset: type: string + description: Asset the payment is denominated in example: USD createdAt: type: string format: date-time + description: When the payment was created raw: type: object nullable: true + description: The provider's original payload, passed through untouched adjustments: type: array + description: Successive changes to the payment's amount and status items: $ref: '#/components/schemas/V2PaymentAdjustment' metadata: $ref: '#/components/schemas/V2PaymentMetadata' V2Connector: type: string + description: The payment provider behind a connector enum: - STRIPE - DUMMY-PAY @@ -3240,16 +3644,22 @@ components: type: integer format: bigint minimum: 0 + description: Amount carried by this adjustment example: 100 date: type: string format: date-time + description: When the adjustment was recorded raw: type: object + description: The provider's original payload for this adjustment absolute: type: boolean + description: Whether amount replaces the payment's amount rather than adding + to it V2PaymentStatus: type: string + description: Where a payment stands in its lifecycle enum: - PENDING - ACTIVE @@ -3262,8 +3672,11 @@ components: properties: key: type: string + description: Metadata value carried by the payment nullable: true + description: Arbitrary key/value pairs attached to a payment V2ActivityDebitWalletOutput: + description: Result of the activity that debits a wallet $ref: '#/components/schemas/V2DebitWalletResponse' V2DebitWalletResponse: type: object @@ -3274,6 +3687,8 @@ components: $ref: '#/components/schemas/V2Hold' V2Hold: type: object + description: Funds locked by a pending wallet debit, later either confirmed + or voided required: - id - walletID @@ -3294,9 +3709,11 @@ components: type: string description: type: string + description: Human-readable reason the funds were held destination: $ref: '#/components/schemas/V2Subject' V2ActivityGetWalletOutput: + description: Result of the activity that reads a wallet $ref: '#/components/schemas/V2GetWalletResponse' V2GetWalletResponse: type: object @@ -3307,6 +3724,7 @@ components: $ref: '#/components/schemas/V2WalletWithBalances' V2WalletWithBalances: type: object + description: A wallet together with the funds it currently holds required: - name - id @@ -3326,11 +3744,14 @@ components: type: string name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created balances: type: object + description: Aggregated funds held by the wallet, keyed by asset required: - main properties: @@ -3338,6 +3759,7 @@ components: $ref: '#/components/schemas/V2AssetHolder' ledger: type: string + description: Name of the ledger backing this wallet V2AssetHolder: type: object required: @@ -3345,11 +3767,13 @@ components: properties: assets: type: object + description: Amounts held, keyed by asset additionalProperties: type: integer format: bigint V2WorkflowInstanceHistoryStageInput: type: object + description: Arguments an activity was called with, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/V2ActivityGetAccount' @@ -3377,6 +3801,7 @@ components: $ref: '#/components/schemas/V2ActivityListWallets' V2WorkflowInstanceHistoryStageOutput: type: object + description: Result an activity returned, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/V2ActivityGetAccountOutput' @@ -3392,6 +3817,7 @@ components: $ref: '#/components/schemas/V2ListWalletsResponse' V2Monetary: type: object + description: An amount together with the asset it is denominated in required: - asset - amount @@ -3405,18 +3831,25 @@ components: description: The amount of the monetary value. V2PostTransaction: type: object + description: A transaction to write to a ledger required: - metadata properties: timestamp: type: string format: date-time + description: >- + The transaction time to record, letting you backdate or postdate the transaction. + See [bi- temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: Fund movements to apply. Mutually exclusive with script items: $ref: '#/components/schemas/V2Posting' script: type: object + description: A Numscript program executed to produce the postings. Mutually + exclusive with postings properties: plain: type: string @@ -3431,11 +3864,14 @@ components: - plain reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, + used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/V2Metadata' V2Metadata: type: object + description: Arbitrary key/value pairs attached to the resource additionalProperties: type: string example: @@ -3447,15 +3883,21 @@ components: type: integer format: bigint minimum: 0 + description: Amount to move, as an arbitrary-precision integer expressed + in the asset's smallest unit example: 100 asset: type: string + description: The asset being moved, optionally carrying a scale suffix such + as USD/2 example: COIN destination: type: string + description: Address of the account credited by this posting example: users:002 source: type: string + description: Address of the account debited by this posting example: users:001 required: - amount @@ -3478,15 +3920,19 @@ components: $ref: '#/components/schemas/V2Trigger' V2Account: type: object + description: An account in the ledger, identified by its address required: - address - metadata properties: address: type: string + description: The account address, a colon-separated segmented path such + as users:001 example: users:001 metadata: type: object + description: Arbitrary key/value pairs attached to the account properties: {} additionalProperties: type: string @@ -3502,12 +3948,15 @@ components: input: type: integer format: bigint + description: Total amount credited for this asset output: type: integer format: bigint + description: Total amount debited for this asset balance: type: integer format: bigint + description: Net balance, equal to input minus output required: - input - output @@ -3517,6 +3966,7 @@ components: balance: 80 V2Volumes: type: object + description: Volumes per asset for a single account additionalProperties: $ref: '#/components/schemas/V2Volume' example: @@ -3537,9 +3987,12 @@ components: $ref: '#/components/schemas/V2TriggerTest' V2TriggerTest: type: object + description: Result of evaluating a trigger against a sample event, without + running the workflow properties: filter: type: object + description: How the trigger's filter evaluated against the sample event properties: match: type: boolean @@ -3547,6 +4000,7 @@ components: type: string variables: type: object + description: The variables the trigger would build from the sample event additionalProperties: type: object properties: diff --git a/openapi/v1.yaml b/openapi/v1.yaml index 0b71127..710c1ad 100644 --- a/openapi/v1.yaml +++ b/openapi/v1.yaml @@ -445,6 +445,7 @@ components: properties: version: type: string + description: Version of the orchestration service Error: type: object required: @@ -453,26 +454,32 @@ components: properties: errorCode: type: string + description: Machine-readable error code identifying the failure enum: - VALIDATION - NOT_FOUND - INTERNAL errorMessage: type: string + description: Human-readable description of the error WorkflowConfig: type: object + description: The stages a workflow runs, in order required: - stages properties: name: type: string + description: Human-readable name for the workflow stages: type: array + description: The stages executed in order when the workflow runs items: type: object additionalProperties: {} Workflow: type: object + description: A workflow definition and the stages it runs required: - config - createdAt @@ -484,11 +491,14 @@ components: createdAt: type: string format: date-time + description: When the workflow was created updatedAt: type: string format: date-time + description: When the workflow was last modified id: type: string + description: Unique identifier of the workflow StageStatus: type: object required: @@ -498,18 +508,24 @@ components: properties: stage: type: number + description: Zero-based position of the stage within the workflow instanceID: type: string + description: Identifier of the workflow instance this stage belongs to startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running error: type: string + description: Why the stage failed, absent when it succeeded WorkflowInstance: type: object + description: One run of a workflow, tracking its per-stage progress required: - workflowID - id @@ -519,25 +535,33 @@ components: properties: workflowID: type: string + description: Identifier of the workflow this run belongs to id: type: string + description: Unique identifier of the run createdAt: type: string format: date-time + description: When the run was started updatedAt: type: string format: date-time + description: When the run was last updated status: type: array + description: Per-stage progress of the run items: $ref: '#/components/schemas/StageStatus' terminated: type: boolean + description: Whether the run has finished, successfully or not terminatedAt: type: string format: date-time + description: When the run finished, absent while it is still running error: type: string + description: Why the run failed, absent when it succeeded workflow: $ref: '#/components/schemas/Workflow' WorkflowInstanceHistoryStage: @@ -551,27 +575,35 @@ components: properties: name: type: string + description: Name of the activity this history entry records input: $ref: '#/components/schemas/WorkflowInstanceHistoryStageInput' output: $ref: '#/components/schemas/WorkflowInstanceHistoryStageOutput' error: type: string + description: Why the activity failed, absent when it succeeded terminated: type: boolean + description: Whether the activity has finished startedAt: type: string format: date-time + description: When the activity started terminatedAt: type: string format: date-time + description: When the activity finished, absent while it is still running lastFailure: type: string + description: Error reported by the most recent failed attempt attempt: type: integer + description: How many times the activity has been attempted nextExecution: type: string format: date-time + description: When the next retry is scheduled, absent once the activity is settled WorkflowInstanceHistory: type: object required: @@ -582,24 +614,31 @@ components: properties: name: type: string + description: Name of the stage this history entry records input: $ref: '#/components/schemas/Stage' error: type: string + description: Why the stage failed, absent when it succeeded terminated: type: boolean + description: Whether the stage has finished startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running WorkflowInstanceHistoryList: type: array + description: Per-stage history of a workflow run items: $ref: '#/components/schemas/WorkflowInstanceHistory' WorkflowInstanceHistoryStageList: type: array + description: Per-activity history of a workflow stage items: $ref: '#/components/schemas/WorkflowInstanceHistoryStage' ListWorkflowsResponse: @@ -609,6 +648,7 @@ components: items: $ref: '#/components/schemas/Workflow' type: array + description: The workflows defined on this stack required: - data TriggerData: @@ -619,18 +659,25 @@ components: properties: event: type: string + description: Type of event that fires this trigger workflowID: type: string + description: Identifier of the workflow to run when the trigger fires version: type: string + description: Version of the trigger definition filter: type: string + description: Expression evaluated against the event. The workflow runs only when it matches vars: type: object + description: Expressions evaluated against the event to build the workflow's input variables additionalProperties: true name: type: string + description: Human-readable name for the trigger Trigger: + description: A rule that starts a workflow when a matching event arrives allOf: - $ref: '#/components/schemas/TriggerData' - type: object @@ -653,17 +700,22 @@ components: date: type: string format: date-time + description: When the trigger fired workflowInstanceID: type: string + description: Identifier of the run the trigger started, absent when it started none workflowInstance: $ref: '#/components/schemas/WorkflowInstance' triggerID: type: string + description: Identifier of the trigger that fired event: type: object + description: The event that fired the trigger additionalProperties: true error: type: string + description: Why the trigger failed to start a run, absent when it succeeded ListTriggersOccurrencesResponse: type: object properties: @@ -671,6 +723,7 @@ components: items: $ref: '#/components/schemas/TriggerOccurrence' type: array + description: The trigger's occurrences required: - data ListTriggersResponse: @@ -680,6 +733,7 @@ components: items: $ref: '#/components/schemas/Trigger' type: array + description: The triggers defined on this stack required: - data CreateWorkflowRequest: @@ -717,6 +771,7 @@ components: items: $ref: '#/components/schemas/WorkflowInstance' type: array + description: The runs of this workflow GetWorkflowResponse: type: object required: @@ -747,24 +802,31 @@ components: $ref: '#/components/schemas/WorkflowInstanceHistoryStageList' StageSendSourceWallet: type: object + description: Take the funds from a wallet required: - id properties: id: type: string + description: Identifier of the wallet to take funds from balance: type: string + description: Name of the balance within the wallet. Defaults to the main balance when omitted StageSendDestinationWallet: + description: Send the funds to a wallet $ref: '#/components/schemas/StageSendSourceWallet' StageSendSourceAccount: type: object + description: Take the funds from a ledger account required: - id properties: id: type: string + description: Address of the ledger account to take funds from ledger: type: string + description: Name of the ledger holding the account throughAccount: type: string description: | @@ -784,14 +846,17 @@ components: default: false example: true StageSendDestinationAccount: + description: Send the funds to a ledger account $ref: '#/components/schemas/StageSendSourceAccount' StageSendSourcePayment: type: object + description: Take the funds from a payment required: - id properties: id: type: string + description: Identifier of the payment to take funds from ledger: type: string description: | @@ -816,6 +881,7 @@ components: default: false StageSendDestinationPayment: type: object + description: Send the funds to a payment required: - psp properties: @@ -843,6 +909,7 @@ components: If not specified, the Payments service may use a default account for the connector. StageSendSource: type: object + description: Where a send stage takes the funds from properties: wallet: $ref: '#/components/schemas/StageSendSourceWallet' @@ -852,6 +919,7 @@ components: $ref: '#/components/schemas/StageSendSourcePayment' StageSendDestination: type: object + description: Where a send stage puts the funds properties: wallet: $ref: '#/components/schemas/StageSendDestinationWallet' @@ -870,19 +938,25 @@ components: $ref: '#/components/schemas/StageSendSource' metadata: type: object + description: Metadata to attach to the resulting transaction additionalProperties: type: string timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) StageDelay: type: object properties: until: type: string format: date-time + description: Wait until this absolute point in time. Mutually exclusive with duration duration: type: string + description: Wait for this long, expressed as a Go duration such as 10s. Mutually exclusive with until StageWaitEvent: type: object required: @@ -890,17 +964,22 @@ components: properties: event: type: string + description: Type of event the workflow waits for before continuing UpdateAccount: type: object + description: Metadata to set on a ledger account properties: id: type: string + description: Address of the ledger account to update metadata: type: object + description: Metadata to set on the account additionalProperties: type: string ledger: type: string + description: Name of the ledger holding the account required: - id - ledger @@ -911,6 +990,7 @@ components: account: $ref: '#/components/schemas/UpdateAccount' Stage: + description: One step of a workflow, whose shape depends on the stage type anyOf: - $ref: '#/components/schemas/StageSend' - $ref: '#/components/schemas/StageDelay' @@ -921,21 +1001,26 @@ components: properties: connectorID: type: string + description: Identifier of the Stripe connector to transfer through amount: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string + description: Stripe connected account receiving the transfer example: acct_1Gqj58KZcSIg2N2q waitingValidation: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -946,12 +1031,14 @@ components: example: order_id: '6735' ActivityStripeTransfer: + description: Arguments for the activity that transfers funds through Stripe $ref: '#/components/schemas/StripeTransferRequest' CreateTransferInitiationRequest: type: object properties: connectorID: type: string + description: Identifier of the connector to transfer through provider: type: string description: | @@ -962,9 +1049,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string @@ -990,6 +1079,7 @@ components: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -998,18 +1088,23 @@ components: example: order_id: '6735' ActivityCreateTransferInitiation: + description: Arguments for the activity that initiates a transfer through a connector $ref: '#/components/schemas/CreateTransferInitiationRequest' ActivityListWallets: type: object + description: Arguments for the activity that lists wallets properties: name: type: string + description: Restrict the listing to wallets with this name ListWalletsResponse: type: object + description: A page of wallets required: - cursor properties: cursor: + description: Paginated cursor wrapping the list of wallets allOf: - $ref: '#/components/schemas/Cursor' - properties: @@ -1040,11 +1135,14 @@ components: description: Metadata associated with the wallet. name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created ledger: type: string + description: Name of the ledger backing this wallet Cursor: type: object required: @@ -1055,35 +1153,46 @@ components: format: int64 minimum: 1 maximum: 1000 + description: Number of items requested per page example: 15 hasMore: type: boolean + description: Whether further pages are available example: false previous: type: string + description: Cursor for the previous page, absent on the first page example: YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol= next: type: string + description: Cursor for the next page, absent on the last page example: '' ActivityGetAccount: type: object + description: Arguments for the activity that reads a ledger account required: - id - ledger properties: id: type: string + description: Address of the ledger account to read ledger: type: string + description: Name of the ledger holding the account ActivityAddAccountMetadata: type: object + description: Arguments for the activity that sets metadata on a ledger account properties: id: type: string + description: Address of the ledger account to update ledger: type: string + description: Name of the ledger holding the account metadata: type: object + description: Metadata to set on the account additionalProperties: type: string required: @@ -1092,44 +1201,56 @@ components: - metadata ActivityCreateTransaction: type: object + description: Arguments for the activity that writes a transaction to a ledger properties: ledger: type: string + description: Name of the ledger to write the transaction to data: $ref: '#/components/schemas/PostTransaction' ActivityRevertTransaction: type: object + description: Arguments for the activity that reverts a ledger transaction required: - id - ledger properties: ledger: type: string + description: Name of the ledger holding the transaction id: type: string + description: Identifier of the transaction to revert ActivityGetPayment: type: object + description: Arguments for the activity that reads a payment required: - id properties: id: type: string + description: Identifier of the payment to read ActivityConfirmHold: type: object + description: Arguments for the activity that confirms a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to confirm ActivityCreditWallet: type: object + description: Arguments for the activity that credits a wallet properties: id: type: string + description: Identifier of the wallet to credit data: $ref: '#/components/schemas/CreditWalletRequest' CreditWalletRequest: type: object + description: A credit to apply to a wallet required: - amount - sources @@ -1144,8 +1265,10 @@ components: description: Metadata associated with the wallet. reference: type: string + description: Optional caller-supplied identifier used to deduplicate the credit sources: type: array + description: Where the funds come from items: $ref: '#/components/schemas/Subject' balance: @@ -1154,6 +1277,9 @@ components: timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) example: amount: asset: USD/2 @@ -1169,8 +1295,10 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a ledger account identifier: type: string + description: Address of the ledger account WalletSubject: type: object required: @@ -1179,11 +1307,15 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a wallet identifier: type: string + description: Identifier of the wallet balance: type: string + description: Name of the balance within the wallet. Defaults to the main balance when omitted Subject: + description: The counterparty of a wallet movement, either a ledger account or another wallet discriminator: propertyName: type mapping: @@ -1194,13 +1326,16 @@ components: - $ref: '#/components/schemas/WalletSubject' ActivityDebitWallet: type: object + description: Arguments for the activity that debits a wallet properties: id: type: string + description: Identifier of the wallet to debit data: $ref: '#/components/schemas/DebitWalletRequest' DebitWalletRequest: type: object + description: A debit to apply to a wallet required: - amount - metadata @@ -1219,10 +1354,12 @@ components: description: Metadata associated with the wallet. description: type: string + description: Human-readable reason for the debit destination: $ref: '#/components/schemas/Subject' balances: type: array + description: Names of the balances to debit from, in order. Defaults to the main balance when omitted items: type: string description: A targeted balance (use '*' for all) @@ -1239,21 +1376,27 @@ components: pending: true ActivityGetWallet: type: object + description: Arguments for the activity that reads a wallet required: - id properties: id: type: string + description: Identifier of the wallet to read ActivityVoidHold: type: object + description: Arguments for the activity that releases a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to release ActivityGetAccountOutput: + description: Result of the activity that reads a ledger account $ref: '#/components/schemas/AccountResponse' ActivityCreateTransactionOutput: + description: Result of the activity that writes a transaction to a ledger $ref: '#/components/schemas/CreateTransactionResponse' CreateTransactionResponse: properties: @@ -1264,16 +1407,22 @@ components: - data Transaction: type: object + description: A transaction recorded in the ledger, carrying its postings and metadata properties: timestamp: type: string format: date-time + description: >- + The transaction time: when the transaction is considered to have occurred. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: The fund movements making up the transaction items: $ref: '#/components/schemas/Posting' reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/Metadata' @@ -1281,8 +1430,10 @@ components: type: integer format: bigint minimum: 0 + description: Unique sequential identifier for this transaction within the ledger reverted: type: boolean + description: Indicates if the transaction has been reverted required: - postings - timestamp @@ -1290,10 +1441,12 @@ components: - metadata - reverted ActivityRevertTransactionOutput: + description: Result of the activity that reverts a ledger transaction $ref: '#/components/schemas/RevertTransactionResponse' RevertTransactionResponse: $ref: '#/components/schemas/CreateTransactionResponse' ActivityGetPaymentOutput: + description: Result of the activity that reads a payment $ref: '#/components/schemas/PaymentResponse' PaymentResponse: type: object @@ -1304,6 +1457,7 @@ components: $ref: '#/components/schemas/Payment' Payment: type: object + description: A payment observed or initiated through a connector required: - id - reference @@ -1322,19 +1476,25 @@ components: properties: id: type: string + description: Unique identifier of the payment example: XXX reference: type: string + description: Identifier the payment carries at the provider sourceAccountID: type: string + description: Identifier of the account the funds left destinationAccountID: type: string + description: Identifier of the account the funds reached connectorID: type: string + description: Identifier of the connector that produced the payment provider: $ref: '#/components/schemas/Connector' type: type: string + description: Direction of the payment enum: - PAY-IN - PAYOUT @@ -1346,9 +1506,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount the payment was created with, before any adjustment example: 100 scheme: type: string + description: Payment scheme or rail the payment travelled over enum: - visa - mastercard @@ -1370,21 +1532,26 @@ components: - other asset: type: string + description: Asset the payment is denominated in example: USD createdAt: type: string format: date-time + description: When the payment was created raw: type: object nullable: true + description: The provider's original payload, passed through untouched adjustments: type: array + description: Successive changes to the payment's amount and status items: $ref: '#/components/schemas/PaymentAdjustment' metadata: $ref: '#/components/schemas/PaymentMetadata' Connector: type: string + description: The payment provider behind a connector enum: - STRIPE - DUMMY-PAY @@ -1409,16 +1576,21 @@ components: type: integer format: bigint minimum: 0 + description: Amount carried by this adjustment example: 100 date: type: string format: date-time + description: When the adjustment was recorded raw: type: object + description: The provider's original payload for this adjustment absolute: type: boolean + description: Whether amount replaces the payment's amount rather than adding to it PaymentStatus: type: string + description: Where a payment stands in its lifecycle enum: - PENDING - ACTIVE @@ -1431,8 +1603,11 @@ components: properties: key: type: string + description: Metadata value carried by the payment nullable: true + description: Arbitrary key/value pairs attached to a payment ActivityDebitWalletOutput: + description: Result of the activity that debits a wallet $ref: '#/components/schemas/DebitWalletResponse' DebitWalletResponse: type: object @@ -1443,6 +1618,7 @@ components: $ref: '#/components/schemas/Hold' Hold: type: object + description: Funds locked by a pending wallet debit, later either confirmed or voided required: - id - walletID @@ -1463,9 +1639,11 @@ components: type: string description: type: string + description: Human-readable reason the funds were held destination: $ref: '#/components/schemas/Subject' ActivityGetWalletOutput: + description: Result of the activity that reads a wallet $ref: '#/components/schemas/GetWalletResponse' GetWalletResponse: type: object @@ -1476,6 +1654,7 @@ components: $ref: '#/components/schemas/WalletWithBalances' WalletWithBalances: type: object + description: A wallet together with the funds it currently holds required: - name - id @@ -1495,11 +1674,14 @@ components: type: string name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created balances: type: object + description: Aggregated funds held by the wallet, keyed by asset required: - main properties: @@ -1507,6 +1689,7 @@ components: $ref: '#/components/schemas/AssetHolder' ledger: type: string + description: Name of the ledger backing this wallet AssetHolder: type: object required: @@ -1514,11 +1697,13 @@ components: properties: assets: type: object + description: Amounts held, keyed by asset additionalProperties: type: integer format: bigint WorkflowInstanceHistoryStageInput: type: object + description: Arguments an activity was called with, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/ActivityGetAccount' @@ -1548,6 +1733,7 @@ components: $ref: '#/components/schemas/ActivityListWallets' WorkflowInstanceHistoryStageOutput: type: object + description: Result an activity returned, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/ActivityGetAccountOutput' @@ -1565,6 +1751,7 @@ components: $ref: '#/components/schemas/ListWalletsResponse' Monetary: type: object + description: An amount together with the asset it is denominated in required: - asset - amount @@ -1578,18 +1765,24 @@ components: description: The amount of the monetary value. PostTransaction: type: object + description: A transaction to write to a ledger required: - metadata properties: timestamp: type: string format: date-time + description: >- + The transaction time to record, letting you backdate or postdate the transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: Fund movements to apply. Mutually exclusive with script items: $ref: '#/components/schemas/Posting' script: type: object + description: A Numscript program executed to produce the postings. Mutually exclusive with postings properties: plain: type: string @@ -1604,11 +1797,13 @@ components: - plain reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/Metadata' Metadata: type: object + description: Arbitrary key/value pairs attached to the resource additionalProperties: type: string example: @@ -1620,15 +1815,19 @@ components: type: integer format: bigint minimum: 0 + description: Amount to move, as an arbitrary-precision integer expressed in the asset's smallest unit example: 100 asset: type: string + description: The asset being moved, optionally carrying a scale suffix such as USD/2 example: COIN destination: type: string + description: Address of the account credited by this posting example: users:002 source: type: string + description: Address of the account debited by this posting example: users:001 required: - amount @@ -1651,15 +1850,18 @@ components: $ref: '#/components/schemas/Trigger' Account: type: object + description: An account in the ledger, identified by its address required: - address - metadata properties: address: type: string + description: The account address, a colon-separated segmented path such as users:001 example: users:001 metadata: type: object + description: Arbitrary key/value pairs attached to the account properties: {} additionalProperties: type: string @@ -1675,12 +1877,15 @@ components: input: type: integer format: bigint + description: Total amount credited for this asset output: type: integer format: bigint + description: Total amount debited for this asset balance: type: integer format: bigint + description: Net balance, equal to input minus output required: - input - output @@ -1690,6 +1895,7 @@ components: balance: 80 Volumes: type: object + description: Volumes per asset for a single account additionalProperties: $ref: '#/components/schemas/Volume' example: diff --git a/openapi/v2.yaml b/openapi/v2.yaml index 0f87545..93a9a82 100644 --- a/openapi/v2.yaml +++ b/openapi/v2.yaml @@ -528,6 +528,7 @@ components: properties: version: type: string + description: Version of the orchestration service V2Error: type: object required: @@ -536,26 +537,32 @@ components: properties: errorCode: type: string + description: Machine-readable error code identifying the failure enum: - VALIDATION - NOT_FOUND - INTERNAL errorMessage: type: string + description: Human-readable description of the error V2WorkflowConfig: type: object + description: The stages a workflow runs, in order required: - stages properties: name: type: string + description: Human-readable name for the workflow stages: type: array + description: The stages executed in order when the workflow runs items: type: object additionalProperties: {} V2Workflow: type: object + description: A workflow definition and the stages it runs required: - config - createdAt @@ -567,11 +574,14 @@ components: createdAt: type: string format: date-time + description: When the workflow was created updatedAt: type: string format: date-time + description: When the workflow was last modified id: type: string + description: Unique identifier of the workflow V2StageStatus: type: object required: @@ -581,18 +591,24 @@ components: properties: stage: type: number + description: Zero-based position of the stage within the workflow instanceID: type: string + description: Identifier of the workflow instance this stage belongs to startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running error: type: string + description: Why the stage failed, absent when it succeeded V2WorkflowInstance: type: object + description: One run of a workflow, tracking its per-stage progress required: - workflowID - id @@ -602,25 +618,33 @@ components: properties: workflowID: type: string + description: Identifier of the workflow this run belongs to id: type: string + description: Unique identifier of the run createdAt: type: string format: date-time + description: When the run was started updatedAt: type: string format: date-time + description: When the run was last updated status: type: array + description: Per-stage progress of the run items: $ref: '#/components/schemas/V2StageStatus' terminated: type: boolean + description: Whether the run has finished, successfully or not terminatedAt: type: string format: date-time + description: When the run finished, absent while it is still running error: type: string + description: Why the run failed, absent when it succeeded workflow: $ref: '#/components/schemas/V2Workflow' V2WorkflowInstanceHistoryStage: @@ -634,27 +658,35 @@ components: properties: name: type: string + description: Name of the activity this history entry records input: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStageInput' output: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStageOutput' error: type: string + description: Why the activity failed, absent when it succeeded terminated: type: boolean + description: Whether the activity has finished startedAt: type: string format: date-time + description: When the activity started terminatedAt: type: string format: date-time + description: When the activity finished, absent while it is still running lastFailure: type: string + description: Error reported by the most recent failed attempt attempt: type: integer + description: How many times the activity has been attempted nextExecution: type: string format: date-time + description: When the next retry is scheduled, absent once the activity is settled V2WorkflowInstanceHistory: type: object required: @@ -665,24 +697,31 @@ components: properties: name: type: string + description: Name of the stage this history entry records input: $ref: '#/components/schemas/V2Stage' error: type: string + description: Why the stage failed, absent when it succeeded terminated: type: boolean + description: Whether the stage has finished startedAt: type: string format: date-time + description: When the stage started terminatedAt: type: string format: date-time + description: When the stage finished, absent while it is still running V2WorkflowInstanceHistoryList: type: array + description: Per-stage history of a workflow run items: $ref: '#/components/schemas/V2WorkflowInstanceHistory' V2WorkflowInstanceHistoryStageList: type: array + description: Per-activity history of a workflow stage items: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStage' V2ListWorkflowsResponse: @@ -690,6 +729,7 @@ components: properties: cursor: type: object + description: Paginated cursor wrapping the list of workflows required: - pageSize - hasMore @@ -724,18 +764,25 @@ components: properties: event: type: string + description: Type of event that fires this trigger workflowID: type: string + description: Identifier of the workflow to run when the trigger fires version: type: string + description: Version of the trigger definition filter: type: string + description: Expression evaluated against the event. The workflow runs only when it matches vars: type: object additionalProperties: true + description: Expressions evaluated against the event to build the workflow's input variables name: type: string + description: Human-readable name for the trigger V2Trigger: + description: A rule that starts a workflow when a matching event arrives allOf: - $ref: '#/components/schemas/V2TriggerData' - type: object @@ -758,22 +805,28 @@ components: date: type: string format: date-time + description: When the trigger fired workflowInstanceID: type: string + description: Identifier of the run the trigger started, absent when it started none workflowInstance: $ref: '#/components/schemas/V2WorkflowInstance' triggerID: type: string + description: Identifier of the trigger that fired error: type: string + description: Why the trigger failed to start a run, absent when it succeeded event: type: object additionalProperties: true + description: The event that fired the trigger V2ListTriggersOccurrencesResponse: type: object properties: cursor: type: object + description: Paginated cursor wrapping the trigger's occurrences required: - pageSize - hasMore @@ -805,6 +858,7 @@ components: properties: cursor: type: object + description: Paginated cursor wrapping the list of triggers required: - pageSize - hasMore @@ -863,6 +917,7 @@ components: properties: cursor: type: object + description: Paginated cursor wrapping the list of runs required: - pageSize - hasMore @@ -919,24 +974,31 @@ components: $ref: '#/components/schemas/V2WorkflowInstanceHistoryStageList' V2StageSendSourceWallet: type: object + description: Take the funds from a wallet required: - id properties: id: type: string + description: Identifier of the wallet to take funds from balance: type: string + description: Name of the balance within the wallet. Defaults to the main balance when omitted V2StageSendDestinationWallet: + description: Send the funds to a wallet $ref: '#/components/schemas/V2StageSendSourceWallet' V2StageSendSourceAccount: type: object + description: Take the funds from a ledger account required: - id properties: id: type: string + description: Address of the ledger account to take funds from ledger: type: string + description: Name of the ledger holding the account throughAccount: type: string description: | @@ -956,14 +1018,17 @@ components: default: false example: true V2StageSendDestinationAccount: + description: Send the funds to a ledger account $ref: '#/components/schemas/V2StageSendSourceAccount' V2StageSendSourcePayment: type: object + description: Take the funds from a payment required: - id properties: id: type: string + description: Identifier of the payment to take funds from ledger: type: string description: | @@ -988,6 +1053,7 @@ components: default: false V2StageSendDestinationPayment: type: object + description: Send the funds to a payment required: - psp properties: @@ -1015,6 +1081,7 @@ components: If not specified, the Payments service may use a default account for the connector. V2StageSendSource: type: object + description: Where a send stage takes the funds from properties: wallet: $ref: '#/components/schemas/V2StageSendSourceWallet' @@ -1024,6 +1091,7 @@ components: $ref: '#/components/schemas/V2StageSendSourcePayment' V2StageSendDestination: type: object + description: Where a send stage puts the funds properties: wallet: $ref: '#/components/schemas/V2StageSendDestinationWallet' @@ -1042,19 +1110,25 @@ components: $ref: '#/components/schemas/V2StageSendSource' metadata: type: object + description: Metadata to attach to the resulting transaction additionalProperties: type: string timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) V2StageDelay: type: object properties: until: type: string format: date-time + description: Wait until this absolute point in time. Mutually exclusive with duration duration: type: string + description: Wait for this long, expressed as a Go duration such as 10s. Mutually exclusive with until V2StageWaitEvent: type: object required: @@ -1062,17 +1136,22 @@ components: properties: event: type: string + description: Type of event the workflow waits for before continuing V2UpdateAccount: type: object + description: Metadata to set on a ledger account properties: id: type: string + description: Address of the ledger account to update metadata: type: object + description: Metadata to set on the account additionalProperties: type: string ledger: type: string + description: Name of the ledger holding the account required: - id - ledger @@ -1083,6 +1162,7 @@ components: account: $ref: '#/components/schemas/V2UpdateAccount' V2Stage: + description: One step of a workflow, whose shape depends on the stage type anyOf: - $ref: '#/components/schemas/V2StageSend' - $ref: '#/components/schemas/V2StageDelay' @@ -1093,21 +1173,26 @@ components: properties: connectorID: type: string + description: Identifier of the Stripe connector to transfer through amount: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string + description: Stripe connected account receiving the transfer example: acct_1Gqj58KZcSIg2N2q waitingValidation: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -1117,12 +1202,14 @@ components: example: order_id: '6735' V2ActivityStripeTransfer: + description: Arguments for the activity that transfers funds through Stripe $ref: '#/components/schemas/V2StripeTransferRequest' V2CreateTransferInitiationRequest: type: object properties: connectorID: type: string + description: Identifier of the connector to transfer through provider: type: string description: | @@ -1133,9 +1220,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount to transfer, in the asset's smallest unit example: 100 asset: type: string + description: Asset the transfer is denominated in example: USD destination: type: string @@ -1161,6 +1250,7 @@ components: type: boolean example: false default: false + description: When true, the transfer is created but held until it is validated metadata: type: object description: > @@ -1169,18 +1259,23 @@ components: example: order_id: '6735' V2ActivityCreateTransferInitiation: + description: Arguments for the activity that initiates a transfer through a connector $ref: '#/components/schemas/V2CreateTransferInitiationRequest' V2ActivityListWallets: type: object + description: Arguments for the activity that lists wallets properties: name: type: string + description: Restrict the listing to wallets with this name V2ListWalletsResponse: type: object + description: A page of wallets required: - cursor properties: cursor: + description: Paginated cursor wrapping the list of wallets allOf: - $ref: '#/components/schemas/V2Cursor' - properties: @@ -1211,11 +1306,14 @@ components: description: Metadata associated with the wallet. name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created ledger: type: string + description: Name of the ledger backing this wallet V2Cursor: type: object required: @@ -1226,35 +1324,46 @@ components: format: int64 minimum: 1 maximum: 1000 + description: Number of items requested per page example: 15 hasMore: type: boolean + description: Whether further pages are available example: false previous: type: string + description: Cursor for the previous page, absent on the first page example: YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol= next: type: string + description: Cursor for the next page, absent on the last page example: '' V2ActivityGetAccount: type: object + description: Arguments for the activity that reads a ledger account required: - id - ledger properties: id: type: string + description: Address of the ledger account to read ledger: type: string + description: Name of the ledger holding the account V2ActivityAddAccountMetadata: type: object + description: Arguments for the activity that sets metadata on a ledger account properties: id: type: string + description: Address of the ledger account to update ledger: type: string + description: Name of the ledger holding the account metadata: type: object + description: Metadata to set on the account additionalProperties: type: string required: @@ -1263,34 +1372,43 @@ components: - metadata V2ActivityCreateTransaction: type: object + description: Arguments for the activity that writes a transaction to a ledger properties: ledger: type: string + description: Name of the ledger to write the transaction to data: $ref: '#/components/schemas/V2PostTransaction' V2ActivityGetPayment: type: object + description: Arguments for the activity that reads a payment required: - id properties: id: type: string + description: Identifier of the payment to read V2ActivityConfirmHold: type: object + description: Arguments for the activity that confirms a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to confirm V2ActivityCreditWallet: type: object + description: Arguments for the activity that credits a wallet properties: id: type: string + description: Identifier of the wallet to credit data: $ref: '#/components/schemas/V2CreditWalletRequest' V2CreditWalletRequest: type: object + description: A credit to apply to a wallet required: - amount - sources @@ -1305,8 +1423,10 @@ components: description: Metadata associated with the wallet. reference: type: string + description: Optional caller-supplied identifier used to deduplicate the credit sources: type: array + description: Where the funds come from items: $ref: '#/components/schemas/V2Subject' balance: @@ -1315,6 +1435,9 @@ components: timestamp: type: string format: date-time + description: >- + The transaction time to record on the resulting transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) example: amount: asset: USD/2 @@ -1330,8 +1453,10 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a ledger account identifier: type: string + description: Address of the ledger account V2WalletSubject: type: object required: @@ -1340,11 +1465,15 @@ components: properties: type: type: string + description: Discriminator identifying this subject as a wallet identifier: type: string + description: Identifier of the wallet balance: type: string + description: Name of the balance within the wallet. Defaults to the main balance when omitted V2Subject: + description: The counterparty of a wallet movement, either a ledger account or another wallet discriminator: propertyName: type mapping: @@ -1355,13 +1484,16 @@ components: - $ref: '#/components/schemas/V2WalletSubject' V2ActivityDebitWallet: type: object + description: Arguments for the activity that debits a wallet properties: id: type: string + description: Identifier of the wallet to debit data: $ref: '#/components/schemas/V2DebitWalletRequest' V2DebitWalletRequest: type: object + description: A debit to apply to a wallet required: - amount - metadata @@ -1379,10 +1511,12 @@ components: description: Metadata associated with the wallet. description: type: string + description: Human-readable reason for the debit destination: $ref: '#/components/schemas/V2Subject' balances: type: array + description: Names of the balances to debit from, in order. Defaults to the main balance when omitted items: type: string description: A targeted balance (use '*' for all) @@ -1399,26 +1533,33 @@ components: pending: true V2ActivityGetWallet: type: object + description: Arguments for the activity that reads a wallet required: - id properties: id: type: string + description: Identifier of the wallet to read V2ActivityVoidHold: type: object + description: Arguments for the activity that releases a wallet hold required: - id properties: id: type: string + description: Identifier of the hold to release V2ActivityGetAccountOutput: + description: Result of the activity that reads a ledger account $ref: '#/components/schemas/V2AccountResponse' V2ActivityCreateTransactionOutput: + description: Result of the activity that writes a transaction to a ledger $ref: '#/components/schemas/V2CreateTransactionResponse' V2CreateTransactionResponse: properties: data: type: array + description: The transactions that were created items: $ref: '#/components/schemas/V2Transaction' type: object @@ -1430,12 +1571,17 @@ components: timestamp: type: string format: date-time + description: >- + The transaction time: when the transaction is considered to have occurred. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: The fund movements making up the transaction items: $ref: '#/components/schemas/V2Posting' reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/V2Metadata' @@ -1443,12 +1589,14 @@ components: type: integer format: bigint minimum: 0 + description: Unique sequential identifier for this transaction within the ledger required: - postings - timestamp - txid - metadata V2ActivityGetPaymentOutput: + description: Result of the activity that reads a payment $ref: '#/components/schemas/V2PaymentResponse' V2PaymentResponse: type: object @@ -1459,6 +1607,7 @@ components: $ref: '#/components/schemas/V2Payment' V2Payment: type: object + description: A payment observed or initiated through a connector required: - id - reference @@ -1477,19 +1626,25 @@ components: properties: id: type: string + description: Unique identifier of the payment example: XXX reference: type: string + description: Identifier the payment carries at the provider sourceAccountID: type: string + description: Identifier of the account the funds left destinationAccountID: type: string + description: Identifier of the account the funds reached connectorID: type: string + description: Identifier of the connector that produced the payment provider: $ref: '#/components/schemas/V2Connector' type: type: string + description: Direction of the payment enum: - PAY-IN - PAYOUT @@ -1501,9 +1656,11 @@ components: type: integer format: bigint minimum: 0 + description: Amount the payment was created with, before any adjustment example: 100 scheme: type: string + description: Payment scheme or rail the payment travelled over enum: - visa - mastercard @@ -1525,21 +1682,26 @@ components: - other asset: type: string + description: Asset the payment is denominated in example: USD createdAt: type: string format: date-time + description: When the payment was created raw: type: object nullable: true + description: The provider's original payload, passed through untouched adjustments: type: array + description: Successive changes to the payment's amount and status items: $ref: '#/components/schemas/V2PaymentAdjustment' metadata: $ref: '#/components/schemas/V2PaymentMetadata' V2Connector: type: string + description: The payment provider behind a connector enum: - STRIPE - DUMMY-PAY @@ -1564,16 +1726,21 @@ components: type: integer format: bigint minimum: 0 + description: Amount carried by this adjustment example: 100 date: type: string format: date-time + description: When the adjustment was recorded raw: type: object + description: The provider's original payload for this adjustment absolute: type: boolean + description: Whether amount replaces the payment's amount rather than adding to it V2PaymentStatus: type: string + description: Where a payment stands in its lifecycle enum: - PENDING - ACTIVE @@ -1586,8 +1753,11 @@ components: properties: key: type: string + description: Metadata value carried by the payment nullable: true + description: Arbitrary key/value pairs attached to a payment V2ActivityDebitWalletOutput: + description: Result of the activity that debits a wallet $ref: '#/components/schemas/V2DebitWalletResponse' V2DebitWalletResponse: type: object @@ -1598,6 +1768,7 @@ components: $ref: '#/components/schemas/V2Hold' V2Hold: type: object + description: Funds locked by a pending wallet debit, later either confirmed or voided required: - id - walletID @@ -1618,9 +1789,11 @@ components: type: string description: type: string + description: Human-readable reason the funds were held destination: $ref: '#/components/schemas/V2Subject' V2ActivityGetWalletOutput: + description: Result of the activity that reads a wallet $ref: '#/components/schemas/V2GetWalletResponse' V2GetWalletResponse: type: object @@ -1631,6 +1804,7 @@ components: $ref: '#/components/schemas/V2WalletWithBalances' V2WalletWithBalances: type: object + description: A wallet together with the funds it currently holds required: - name - id @@ -1650,11 +1824,14 @@ components: type: string name: type: string + description: Human-readable name of the wallet createdAt: type: string format: date-time + description: When the wallet was created balances: type: object + description: Aggregated funds held by the wallet, keyed by asset required: - main properties: @@ -1662,6 +1839,7 @@ components: $ref: '#/components/schemas/V2AssetHolder' ledger: type: string + description: Name of the ledger backing this wallet V2AssetHolder: type: object required: @@ -1669,11 +1847,13 @@ components: properties: assets: type: object + description: Amounts held, keyed by asset additionalProperties: type: integer format: bigint V2WorkflowInstanceHistoryStageInput: type: object + description: Arguments an activity was called with, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/V2ActivityGetAccount' @@ -1701,6 +1881,7 @@ components: $ref: '#/components/schemas/V2ActivityListWallets' V2WorkflowInstanceHistoryStageOutput: type: object + description: Result an activity returned, keyed by activity name properties: GetAccount: $ref: '#/components/schemas/V2ActivityGetAccountOutput' @@ -1716,6 +1897,7 @@ components: $ref: '#/components/schemas/V2ListWalletsResponse' V2Monetary: type: object + description: An amount together with the asset it is denominated in required: - asset - amount @@ -1729,18 +1911,24 @@ components: description: The amount of the monetary value. V2PostTransaction: type: object + description: A transaction to write to a ledger required: - metadata properties: timestamp: type: string format: date-time + description: >- + The transaction time to record, letting you backdate or postdate the transaction. See [bi- + temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) postings: type: array + description: Fund movements to apply. Mutually exclusive with script items: $ref: '#/components/schemas/V2Posting' script: type: object + description: A Numscript program executed to produce the postings. Mutually exclusive with postings properties: plain: type: string @@ -1767,11 +1955,13 @@ components: - plain reference: type: string + description: Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions example: ref:001 metadata: $ref: '#/components/schemas/V2Metadata' V2Metadata: type: object + description: Arbitrary key/value pairs attached to the resource additionalProperties: type: string example: @@ -1783,15 +1973,19 @@ components: type: integer format: bigint minimum: 0 + description: Amount to move, as an arbitrary-precision integer expressed in the asset's smallest unit example: 100 asset: type: string + description: The asset being moved, optionally carrying a scale suffix such as USD/2 example: COIN destination: type: string + description: Address of the account credited by this posting example: users:002 source: type: string + description: Address of the account debited by this posting example: users:001 required: - amount @@ -1814,15 +2008,18 @@ components: $ref: '#/components/schemas/V2Trigger' V2Account: type: object + description: An account in the ledger, identified by its address required: - address - metadata properties: address: type: string + description: The account address, a colon-separated segmented path such as users:001 example: users:001 metadata: type: object + description: Arbitrary key/value pairs attached to the account properties: {} additionalProperties: type: string @@ -1838,12 +2035,15 @@ components: input: type: integer format: bigint + description: Total amount credited for this asset output: type: integer format: bigint + description: Total amount debited for this asset balance: type: integer format: bigint + description: Net balance, equal to input minus output required: - input - output @@ -1853,6 +2053,7 @@ components: balance: 80 V2Volumes: type: object + description: Volumes per asset for a single account additionalProperties: $ref: '#/components/schemas/V2Volume' example: @@ -1873,9 +2074,11 @@ components: $ref: '#/components/schemas/V2TriggerTest' V2TriggerTest: type: object + description: Result of evaluating a trigger against a sample event, without running the workflow properties: filter: type: object + description: How the trigger's filter evaluated against the sample event properties: match: type: boolean @@ -1883,6 +2086,7 @@ components: type: string variables: type: object + description: The variables the trigger would build from the sample event additionalProperties: type: object properties: From e6fc5a05859f8b9bde7eb1fbd5d4ff9771c64bbe Mon Sep 17 00:00:00 2001 From: Ariel Yahav Date: Fri, 21 Aug 2026 10:56:42 +0100 Subject: [PATCH 2/2] fix(openapi): wrap described $ref schemas in allOf This spec is OpenAPI 3.0.3, where siblings of a $ref are ignored, so the 19 descriptions I put next to a bare $ref would never have reached the generated docs or SDK comments. Wrapping each reference in a single-member allOf puts the description on the containing schema, where it is read. A one-member allOf validates identically to the bare $ref, so this is an annotation fix with no effect on request or response shapes. --- openapi.yaml | 57 ++++++++++++++++++++++++++++++++----------------- openapi/v1.yaml | 30 +++++++++++++++++--------- openapi/v2.yaml | 27 +++++++++++++++-------- 3 files changed, 76 insertions(+), 38 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 845b475..5b9edbd 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1315,7 +1315,8 @@ components: balance when omitted StageSendDestinationWallet: description: Send the funds to a wallet - $ref: '#/components/schemas/StageSendSourceWallet' + allOf: + - $ref: '#/components/schemas/StageSendSourceWallet' StageSendSourceAccount: type: object description: Take the funds from a ledger account @@ -1348,7 +1349,8 @@ components: example: true StageSendDestinationAccount: description: Send the funds to a ledger account - $ref: '#/components/schemas/StageSendSourceAccount' + allOf: + - $ref: '#/components/schemas/StageSendSourceAccount' StageSendSourcePayment: type: object description: Take the funds from a payment @@ -1535,7 +1537,8 @@ components: order_id: '6735' ActivityStripeTransfer: description: Arguments for the activity that transfers funds through Stripe - $ref: '#/components/schemas/StripeTransferRequest' + allOf: + - $ref: '#/components/schemas/StripeTransferRequest' CreateTransferInitiationRequest: type: object properties: @@ -1593,7 +1596,8 @@ components: ActivityCreateTransferInitiation: description: Arguments for the activity that initiates a transfer through a connector - $ref: '#/components/schemas/CreateTransferInitiationRequest' + allOf: + - $ref: '#/components/schemas/CreateTransferInitiationRequest' ActivityListWallets: type: object description: Arguments for the activity that lists wallets @@ -1901,10 +1905,12 @@ components: description: Identifier of the hold to release ActivityGetAccountOutput: description: Result of the activity that reads a ledger account - $ref: '#/components/schemas/AccountResponse' + allOf: + - $ref: '#/components/schemas/AccountResponse' ActivityCreateTransactionOutput: description: Result of the activity that writes a transaction to a ledger - $ref: '#/components/schemas/CreateTransactionResponse' + allOf: + - $ref: '#/components/schemas/CreateTransactionResponse' CreateTransactionResponse: properties: data: @@ -1952,12 +1958,14 @@ components: - reverted ActivityRevertTransactionOutput: description: Result of the activity that reverts a ledger transaction - $ref: '#/components/schemas/RevertTransactionResponse' + allOf: + - $ref: '#/components/schemas/RevertTransactionResponse' RevertTransactionResponse: $ref: '#/components/schemas/CreateTransactionResponse' ActivityGetPaymentOutput: description: Result of the activity that reads a payment - $ref: '#/components/schemas/PaymentResponse' + allOf: + - $ref: '#/components/schemas/PaymentResponse' PaymentResponse: type: object required: @@ -2119,7 +2127,8 @@ components: description: Arbitrary key/value pairs attached to a payment ActivityDebitWalletOutput: description: Result of the activity that debits a wallet - $ref: '#/components/schemas/DebitWalletResponse' + allOf: + - $ref: '#/components/schemas/DebitWalletResponse' DebitWalletResponse: type: object required: @@ -2156,7 +2165,8 @@ components: $ref: '#/components/schemas/Subject' ActivityGetWalletOutput: description: Result of the activity that reads a wallet - $ref: '#/components/schemas/GetWalletResponse' + allOf: + - $ref: '#/components/schemas/GetWalletResponse' GetWalletResponse: type: object required: @@ -2894,7 +2904,8 @@ components: balance when omitted V2StageSendDestinationWallet: description: Send the funds to a wallet - $ref: '#/components/schemas/V2StageSendSourceWallet' + allOf: + - $ref: '#/components/schemas/V2StageSendSourceWallet' V2StageSendSourceAccount: type: object description: Take the funds from a ledger account @@ -2927,7 +2938,8 @@ components: example: true V2StageSendDestinationAccount: description: Send the funds to a ledger account - $ref: '#/components/schemas/V2StageSendSourceAccount' + allOf: + - $ref: '#/components/schemas/V2StageSendSourceAccount' V2StageSendSourcePayment: type: object description: Take the funds from a payment @@ -3114,7 +3126,8 @@ components: order_id: '6735' V2ActivityStripeTransfer: description: Arguments for the activity that transfers funds through Stripe - $ref: '#/components/schemas/V2StripeTransferRequest' + allOf: + - $ref: '#/components/schemas/V2StripeTransferRequest' V2CreateTransferInitiationRequest: type: object properties: @@ -3172,7 +3185,8 @@ components: V2ActivityCreateTransferInitiation: description: Arguments for the activity that initiates a transfer through a connector - $ref: '#/components/schemas/V2CreateTransferInitiationRequest' + allOf: + - $ref: '#/components/schemas/V2CreateTransferInitiationRequest' V2ActivityListWallets: type: object description: Arguments for the activity that lists wallets @@ -3467,10 +3481,12 @@ components: description: Identifier of the hold to release V2ActivityGetAccountOutput: description: Result of the activity that reads a ledger account - $ref: '#/components/schemas/V2AccountResponse' + allOf: + - $ref: '#/components/schemas/V2AccountResponse' V2ActivityCreateTransactionOutput: description: Result of the activity that writes a transaction to a ledger - $ref: '#/components/schemas/V2CreateTransactionResponse' + allOf: + - $ref: '#/components/schemas/V2CreateTransactionResponse' V2CreateTransactionResponse: properties: data: @@ -3515,7 +3531,8 @@ components: - metadata V2ActivityGetPaymentOutput: description: Result of the activity that reads a payment - $ref: '#/components/schemas/V2PaymentResponse' + allOf: + - $ref: '#/components/schemas/V2PaymentResponse' V2PaymentResponse: type: object required: @@ -3677,7 +3694,8 @@ components: description: Arbitrary key/value pairs attached to a payment V2ActivityDebitWalletOutput: description: Result of the activity that debits a wallet - $ref: '#/components/schemas/V2DebitWalletResponse' + allOf: + - $ref: '#/components/schemas/V2DebitWalletResponse' V2DebitWalletResponse: type: object required: @@ -3714,7 +3732,8 @@ components: $ref: '#/components/schemas/V2Subject' V2ActivityGetWalletOutput: description: Result of the activity that reads a wallet - $ref: '#/components/schemas/V2GetWalletResponse' + allOf: + - $ref: '#/components/schemas/V2GetWalletResponse' V2GetWalletResponse: type: object required: diff --git a/openapi/v1.yaml b/openapi/v1.yaml index 710c1ad..cb73677 100644 --- a/openapi/v1.yaml +++ b/openapi/v1.yaml @@ -814,7 +814,8 @@ components: description: Name of the balance within the wallet. Defaults to the main balance when omitted StageSendDestinationWallet: description: Send the funds to a wallet - $ref: '#/components/schemas/StageSendSourceWallet' + allOf: + - $ref: '#/components/schemas/StageSendSourceWallet' StageSendSourceAccount: type: object description: Take the funds from a ledger account @@ -847,7 +848,8 @@ components: example: true StageSendDestinationAccount: description: Send the funds to a ledger account - $ref: '#/components/schemas/StageSendSourceAccount' + allOf: + - $ref: '#/components/schemas/StageSendSourceAccount' StageSendSourcePayment: type: object description: Take the funds from a payment @@ -1032,7 +1034,8 @@ components: order_id: '6735' ActivityStripeTransfer: description: Arguments for the activity that transfers funds through Stripe - $ref: '#/components/schemas/StripeTransferRequest' + allOf: + - $ref: '#/components/schemas/StripeTransferRequest' CreateTransferInitiationRequest: type: object properties: @@ -1089,7 +1092,8 @@ components: order_id: '6735' ActivityCreateTransferInitiation: description: Arguments for the activity that initiates a transfer through a connector - $ref: '#/components/schemas/CreateTransferInitiationRequest' + allOf: + - $ref: '#/components/schemas/CreateTransferInitiationRequest' ActivityListWallets: type: object description: Arguments for the activity that lists wallets @@ -1394,10 +1398,12 @@ components: description: Identifier of the hold to release ActivityGetAccountOutput: description: Result of the activity that reads a ledger account - $ref: '#/components/schemas/AccountResponse' + allOf: + - $ref: '#/components/schemas/AccountResponse' ActivityCreateTransactionOutput: description: Result of the activity that writes a transaction to a ledger - $ref: '#/components/schemas/CreateTransactionResponse' + allOf: + - $ref: '#/components/schemas/CreateTransactionResponse' CreateTransactionResponse: properties: data: @@ -1442,12 +1448,14 @@ components: - reverted ActivityRevertTransactionOutput: description: Result of the activity that reverts a ledger transaction - $ref: '#/components/schemas/RevertTransactionResponse' + allOf: + - $ref: '#/components/schemas/RevertTransactionResponse' RevertTransactionResponse: $ref: '#/components/schemas/CreateTransactionResponse' ActivityGetPaymentOutput: description: Result of the activity that reads a payment - $ref: '#/components/schemas/PaymentResponse' + allOf: + - $ref: '#/components/schemas/PaymentResponse' PaymentResponse: type: object required: @@ -1608,7 +1616,8 @@ components: description: Arbitrary key/value pairs attached to a payment ActivityDebitWalletOutput: description: Result of the activity that debits a wallet - $ref: '#/components/schemas/DebitWalletResponse' + allOf: + - $ref: '#/components/schemas/DebitWalletResponse' DebitWalletResponse: type: object required: @@ -1644,7 +1653,8 @@ components: $ref: '#/components/schemas/Subject' ActivityGetWalletOutput: description: Result of the activity that reads a wallet - $ref: '#/components/schemas/GetWalletResponse' + allOf: + - $ref: '#/components/schemas/GetWalletResponse' GetWalletResponse: type: object required: diff --git a/openapi/v2.yaml b/openapi/v2.yaml index 93a9a82..c8c5cb4 100644 --- a/openapi/v2.yaml +++ b/openapi/v2.yaml @@ -986,7 +986,8 @@ components: description: Name of the balance within the wallet. Defaults to the main balance when omitted V2StageSendDestinationWallet: description: Send the funds to a wallet - $ref: '#/components/schemas/V2StageSendSourceWallet' + allOf: + - $ref: '#/components/schemas/V2StageSendSourceWallet' V2StageSendSourceAccount: type: object description: Take the funds from a ledger account @@ -1019,7 +1020,8 @@ components: example: true V2StageSendDestinationAccount: description: Send the funds to a ledger account - $ref: '#/components/schemas/V2StageSendSourceAccount' + allOf: + - $ref: '#/components/schemas/V2StageSendSourceAccount' V2StageSendSourcePayment: type: object description: Take the funds from a payment @@ -1203,7 +1205,8 @@ components: order_id: '6735' V2ActivityStripeTransfer: description: Arguments for the activity that transfers funds through Stripe - $ref: '#/components/schemas/V2StripeTransferRequest' + allOf: + - $ref: '#/components/schemas/V2StripeTransferRequest' V2CreateTransferInitiationRequest: type: object properties: @@ -1260,7 +1263,8 @@ components: order_id: '6735' V2ActivityCreateTransferInitiation: description: Arguments for the activity that initiates a transfer through a connector - $ref: '#/components/schemas/V2CreateTransferInitiationRequest' + allOf: + - $ref: '#/components/schemas/V2CreateTransferInitiationRequest' V2ActivityListWallets: type: object description: Arguments for the activity that lists wallets @@ -1551,10 +1555,12 @@ components: description: Identifier of the hold to release V2ActivityGetAccountOutput: description: Result of the activity that reads a ledger account - $ref: '#/components/schemas/V2AccountResponse' + allOf: + - $ref: '#/components/schemas/V2AccountResponse' V2ActivityCreateTransactionOutput: description: Result of the activity that writes a transaction to a ledger - $ref: '#/components/schemas/V2CreateTransactionResponse' + allOf: + - $ref: '#/components/schemas/V2CreateTransactionResponse' V2CreateTransactionResponse: properties: data: @@ -1597,7 +1603,8 @@ components: - metadata V2ActivityGetPaymentOutput: description: Result of the activity that reads a payment - $ref: '#/components/schemas/V2PaymentResponse' + allOf: + - $ref: '#/components/schemas/V2PaymentResponse' V2PaymentResponse: type: object required: @@ -1758,7 +1765,8 @@ components: description: Arbitrary key/value pairs attached to a payment V2ActivityDebitWalletOutput: description: Result of the activity that debits a wallet - $ref: '#/components/schemas/V2DebitWalletResponse' + allOf: + - $ref: '#/components/schemas/V2DebitWalletResponse' V2DebitWalletResponse: type: object required: @@ -1794,7 +1802,8 @@ components: $ref: '#/components/schemas/V2Subject' V2ActivityGetWalletOutput: description: Result of the activity that reads a wallet - $ref: '#/components/schemas/V2GetWalletResponse' + allOf: + - $ref: '#/components/schemas/V2GetWalletResponse' V2GetWalletResponse: type: object required: