fix: separating create customer from customer response schemas

[pengying]

TL;DR

Refactored customer schema definitions to use a consistent approach for both creation and update operations.

What changed?

• Created new schema definitions for customer creation requests:
  • CustomerCreateRequest as a base schema
  • IndividualCustomerCreateRequest and BusinessCustomerCreateRequest extending the base schema
  • CustomerCreateRequestOneOf to handle the oneOf relationship between customer types
• Replaced the separate update schemas (IndividualCustomerUpdate and BusinessCustomerUpdate) with the same creation request schemas
• Updated API endpoints to reference the new schema definitions:
  • Changed POST /customers to use CustomerCreateRequestOneOf
  • Changed PATCH /customers/{customerId} to use CustomerCreateRequestOneOf

[pengying]

• fix: separating create customer from customer response schemas #142 👈 (View in Graphite)
• main

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

[greptile-apps]

Greptile Overview

Greptile Summary

This PR refactors customer schema definitions to create a cleaner separation between creation and update operations using shared field definitions.

Key Changes

• New base schemas: Created CustomerCreateRequest and CustomerUpdateRequest as base schemas containing common fields (customerType, platformCustomerId, umaAddress)
• Shared field definitions: Introduced IndividualCustomerFields and BusinessCustomerFields to eliminate duplication across request and response schemas
• Business info separation: Split business information into BusinessInfo.yaml (optional fields for updates) and BusinessInfoRequired.yaml (requires legalName for creation)
• Schema composition: All customer request schemas now use allOf pattern to combine base schemas with type-specific fields
• Endpoint updates: Both POST /customers and PATCH /customers/{customerId} now reference the new schema structure through CustomerCreateRequestOneOf and CustomerUpdateRequestOneOf

Architecture Benefits

The refactoring improves schema maintainability by:

1. Eliminating duplication through shared field definitions
2. Separating required fields for creation vs optional fields for updates
3. Using consistent allOf composition pattern across all schemas
4. Making the response schemas (IndividualCustomer, BusinessCustomer) reuse the same field definitions

Issues Already Reported

Previous review comments identified issues with CustomerCreateRequest.yaml including:

• Missing type: string declaration for umaAddress
• Duplicated description text in umaAddress field
• platformCustomerId marked as required but described as optional
• Description mentions "customer creation" only but schema used for both create and update operations

These issues are acknowledged by the development team.

Confidence Score: 4/5

• This PR is safe to merge after addressing the schema definition issues in CustomerCreateRequest.yaml
• The refactoring is architecturally sound with proper separation of create/update schemas and shared field definitions. The schema composition correctly uses allOf patterns and properly handles required vs optional fields. However, the score is reduced to 4 due to existing issues in CustomerCreateRequest.yaml (missing type declaration, duplicated text, inconsistent required field documentation) that should be fixed before merge. The update path correctly supports partial updates through BusinessInfo.yaml without required fields.
• openapi/components/schemas/customers/CustomerCreateRequest.yaml needs fixes for type declaration and description issues

Important Files Changed

Filename	Overview
openapi/components/schemas/customers/CustomerCreateRequest.yaml	New base schema for customer creation with required platformCustomerId and duplicated umaAddress description
openapi/components/schemas/customers/CustomerUpdateRequest.yaml	New base schema for customer updates, properly designed with optional fields for partial updates
openapi/components/schemas/customers/BusinessCustomerCreateRequest.yaml	Combines base schema with business fields and overrides to require legalName for creation
openapi/components/schemas/customers/BusinessCustomerUpdateRequest.yaml	Properly allows partial updates by using BusinessInfo.yaml without required fields
openapi/components/schemas/customers/BusinessInfoRequired.yaml	Business information schema requiring legalName for customer creation
openapi/paths/customers/customers.yaml	Updated POST endpoint to reference new CustomerCreateRequestOneOf schema
openapi/paths/customers/customers_{customerId}.yaml	Updated PATCH endpoint to reference new CustomerUpdateRequestOneOf schema

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Grid API
    participant CreateSchema as CustomerCreateRequestOneOf
    participant UpdateSchema as CustomerUpdateRequestOneOf
    participant Response as Customer Response

    Note over Client,Response: Customer Creation Flow (POST /customers)
    Client->>API: POST /customers
    API->>CreateSchema: Validate against schema
    alt Individual Customer
        CreateSchema->>CreateSchema: CustomerCreateRequest (base)<br/>+ IndividualCustomerFields<br/>Requires: customerType, platformCustomerId
    else Business Customer
        CreateSchema->>CreateSchema: CustomerCreateRequest (base)<br/>+ BusinessCustomerFields<br/>+ BusinessInfoRequired override<br/>Requires: customerType, platformCustomerId, legalName
    end
    CreateSchema-->>API: Validation passed
    API->>Response: Return Customer (with generated IDs)
    Response-->>Client: 201 Created

    Note over Client,Response: Customer Update Flow (PATCH /customers/{customerId})
    Client->>API: PATCH /customers/{customerId}
    API->>UpdateSchema: Validate against schema
    alt Individual Customer
        UpdateSchema->>UpdateSchema: CustomerUpdateRequest (base)<br/>+ IndividualCustomerFields<br/>Requires: customerType only<br/>All other fields optional
    else Business Customer
        UpdateSchema->>UpdateSchema: CustomerUpdateRequest (base)<br/>+ BusinessCustomerFields<br/>Requires: customerType only<br/>businessInfo fields all optional (BusinessInfo.yaml)
    end
    UpdateSchema-->>API: Validation passed (partial update)
    API->>Response: Return updated Customer
    Response-->>Client: 200 OK

Loading

[greptile-apps]

_{4 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{3 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{7 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}