feat: add Quote/Transaction discriminators and remove inline examples

[pengying]

TL;DR

Refactored OpenAPI schema to use proper discriminators for polymorphic types in transaction and quote models.

What changed?

• Added proper discriminator fields (sourceType and destinationType) to polymorphic types in the API schema
• Extracted reusable schema components into separate files for better organization:
  • Created dedicated schema files for source and destination types (Account, UMA Address)
  • Added proper type discriminators to enable client code generation tools to handle polymorphism correctly
• Removed inline examples from the /quotes endpoint request body
• Removed redundant examples from schema definitions that were duplicated across multiple components

[pengying]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: add Stainless SDK config and misc cleanups #132
• feat: rename Error to GridError and add additionalProperties to error schemas #131
• feat: add Customer API discriminators and consolidate customer changes #130
• feat: add Quote/Transaction discriminators and remove inline examples #129 👈 (View in Graphite)
• feat: add isPlatformAccount to PaymentInstructions and remove PaymentAccountOrWalletInfo refs #128
• feat: rename accounts to data in list external accounts response #127
• feat: convert single-value enums to const for base types #126
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR refactors the OpenAPI schema to implement proper discriminator patterns for polymorphic types in quotes and transactions, significantly improving code generation capabilities.

Key changes:

• Added sourceType and destinationType discriminator fields to all polymorphic source/destination schemas
• Extracted inline type definitions into dedicated schema files (AccountSource.yaml, UmaAddressSource.yaml, AccountDestination.yaml, UmaAddressDestination.yaml, etc.)
• Implemented OpenAPI 3.1 discriminator mappings in Transaction, Quote, QuoteRequest, IncomingTransaction, and OutgoingTransaction schemas
• Removed inline examples from /quotes endpoint and schema definitions to avoid duplication
• Maintained backward compatibility by using const fields for discriminator values

Impact:
This change enables OpenAPI code generators to properly create type-safe discriminated unions in client libraries, making it easier for developers to work with polymorphic API responses. The discriminator pattern is an industry best practice for handling inheritance and polymorphism in OpenAPI specifications.

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• The changes are purely structural improvements to the OpenAPI schema that enhance code generation without modifying API behavior. All discriminator patterns follow OpenAPI 3.1 specifications correctly, with proper const values and mapping definitions. The refactoring extracts inline definitions into reusable components, improving maintainability and consistency across the schema.
• No files require special attention

Important Files Changed

Filename	Overview
openapi/components/schemas/transactions/Transaction.yaml	Refactored to use discriminator pattern for polymorphic destination types, improving code generation
openapi/components/schemas/transactions/AccountSource.yaml	New schema file with sourceType discriminator field for account source type
openapi/components/schemas/transactions/AccountDestination.yaml	New schema file with destinationType discriminator field for account destination type
openapi/components/schemas/quotes/Quote.yaml	Refactored destination to use discriminator pattern, removed inline examples from paymentInstructions
openapi/components/schemas/quotes/QuoteSource.yaml	Updated to use discriminator pattern with sourceType for polymorphic quote sources
openapi/components/schemas/quotes/QuoteRequest.yaml	Updated to use discriminator pattern for polymorphic destination types in quote requests
openapi/paths/quotes/quotes.yaml	Removed inline examples from POST request body, delegating examples to schema definitions

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Grid API
    participant Schema as OpenAPI Schema
    participant CodeGen as Code Generator

    Note over Client,CodeGen: Quote Creation Flow with Discriminators

    Client->>API: POST /quotes<br/>{source: {sourceType: "ACCOUNT", ...}, <br/>destination: {destinationType: "UMA_ADDRESS", ...}}
    API->>Schema: Validate request against QuoteRequest schema
    Schema->>Schema: Check discriminator.propertyName: "sourceType"
    Schema->>Schema: Route to QuoteAccountSource via mapping
    Schema->>Schema: Check discriminator.propertyName: "destinationType"
    Schema->>Schema: Route to QuoteRequestUmaAddressDestination via mapping
    Schema-->>API: Validation successful
    API->>API: Create quote with typed source/destination
    API-->>Client: 201 Created<br/>{quoteId, source: {sourceType: "ACCOUNT"}, <br/>destination: {destinationType: "UMA_ADDRESS"}}

    Note over Client,CodeGen: Transaction Retrieval Flow

    Client->>API: GET /transactions/{id}
    API->>API: Retrieve transaction
    API->>Schema: Serialize with Transaction schema
    Schema->>Schema: Apply discriminator for type: OUTGOING
    Schema->>Schema: Include source with sourceType discriminator
    Schema->>Schema: Include destination with destinationType discriminator
    API-->>Client: 200 OK<br/>{type: "OUTGOING", <br/>source: {sourceType: "ACCOUNT"}, <br/>destination: {destinationType: "UMA_ADDRESS"}}

    Note over CodeGen: Code Generation Benefits

    CodeGen->>Schema: Parse OpenAPI spec
    Schema-->>CodeGen: Discriminator mappings found
    CodeGen->>CodeGen: Generate type-safe unions<br/>with discriminated types
    CodeGen->>CodeGen: Create proper inheritance/polymorphism<br/>in target language

Loading