fix: align bulk delete error contracts

[Aniruddha-Shriwant]

Summary

• document runtime InvalidUsage responses for bulk-delete 400 and 403 cases
• allow BulkError response arrays for bulk-delete validation failures
• add missing 400 responses to cost-center and per-diem delete-summary endpoints
• regenerate the admin OpenAPI bundle

Validation

• platform API groups 0300: 63 passed
• platform API groups 1000: 76 passed

ClickUp

https://app.clickup.com/

[Copilot]

Pull request overview

This PR updates the Admin OpenAPI spec to standardize bulk delete error response schemas by introducing reusable error schema components and referencing them from several bulk delete and bulk delete-summary endpoints.

Changes:

• Added invalid_usage_error and bulk_action_error schema components for consistent error modeling.
• Updated multiple Admin bulk delete endpoints to reference the shared error schemas instead of inline error objects.
• Regenerated reference/admin.yaml to reflect the updated component schemas and endpoint responses.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/components/schemas/invalid_usage_error.yaml	Adds a reusable schema for InvalidUsage errors.
src/components/schemas/bulk_action_error.yaml	Adds a reusable oneOf schema covering InvalidUsage and BulkError response bodies.
src/admin/paths/admin@per_diem_rates@delete@bulk.yaml	Switches 400/403 error schemas to shared components for bulk delete.
src/admin/paths/admin@per_diem_rates@delete_summary@bulk.yaml	Adds 400 error schema and updates 403 schema reference to shared components.
src/admin/paths/admin@mileage_rates@delete@bulk.yaml	Switches 400/403 error schemas to shared components for bulk delete.
src/admin/paths/admin@mileage_rates@delete_summary@bulk.yaml	Switches 400/403 error schemas to shared components for delete summary.
src/admin/paths/admin@levels@delete@bulk.yaml	Switches 400/403 error schemas to shared components for bulk delete.
src/admin/paths/admin@levels@delete_summary@bulk.yaml	Switches 400/403 error schemas to shared components for delete summary.
src/admin/paths/admin@departments@delete@bulk.yaml	Switches 400/403 error schemas to shared components for bulk delete.
src/admin/paths/admin@departments@delete_summary@bulk.yaml	Switches 400/403 error schemas to shared components for delete summary.
src/admin/paths/admin@cost_centers@delete@bulk.yaml	Switches 400/403 error schemas to shared components for bulk delete.
src/admin/paths/admin@cost_centers@delete_summary@bulk.yaml	Adds 400 error schema and updates 403 schema reference to shared components.
reference/admin.yaml	Updates the bundled Admin reference spec to include the new components and updated endpoint schemas.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (11)

src/admin/paths/admin@cost_centers@delete@bulk.yaml:40

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@per_diem_rates@delete@bulk.yaml:40

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@mileage_rates@delete@bulk.yaml:65

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@levels@delete@bulk.yaml:65

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@departments@delete@bulk.yaml:65

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@cost_centers@delete_summary@bulk.yaml:47

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@per_diem_rates@delete_summary@bulk.yaml:47

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@mileage_rates@delete_summary@bulk.yaml:57

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@levels@delete_summary@bulk.yaml:57

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/admin/paths/admin@departments@delete_summary@bulk.yaml:58

• This 403 response is documented as "Forbidden" but now references invalid_usage_error (error=InvalidUsage). That conflicts with the existing 403.yaml contract (message=Forbidden) and makes it unclear what payload clients should expect. Consider documenting both shapes for 403 via oneOf (Forbidden vs InvalidUsage).

    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/invalid_usage_error.yaml'

src/components/schemas/invalid_usage_error.yaml:18

• message is used as nullable: true in existing InvalidUsage error payload docs (e.g., src/admin/paths/admin@projects@delete@bulk.yaml:48-58), but this new shared schema makes message non-nullable. That would make the shared contract stricter than other endpoints and may reject null messages.

  message:
    type: string
    description: Human-readable description of why the action was rejected.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/components/schemas/invalid_usage_error.yaml:18

• Most existing InvalidUsage/400-style error schemas in this repo allow message to be nullable (e.g., src/components/schemas/400.yaml). Making message non-nullable here is a stricter contract and may break clients if the API ever returns message: null for InvalidUsage errors.

  message:
    type: string
    description: Human-readable description of why the action was rejected.

src/components/schemas/bulk_action_forbidden_error.yaml:2

• Using oneOf here can become invalid if an error payload happens to satisfy both referenced schemas (e.g., a payload shaped like invalid_usage_error with message "Forbidden" would also validate against 403.yaml because it doesn't forbid extra properties). Switching to anyOf avoids runtime schema-validation failures while still expressing that either shape may be returned.

oneOf:

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.