Skip to content

refactor: openapi dedupe errors - #133

Closed
oericdacosta wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
oericdacosta:refactor/openapi-dedupe-errors
Closed

oericdacosta wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
oericdacosta:refactor/openapi-dedupe-errors

Conversation

@oericdacosta

Copy link
Copy Markdown

refactor: deduplicate parameters and standardize error responses

Description

This PR refactors the Shopping Service OpenAPI specification source/services/shopping/openapi.json to improve maintainability and strictly follow the DRY principle.

Key Changes:

  1. Deduplicated Header Parameters: Moved 9 common header parameters (e.g., Authorization, X-API-Key, Request-Id) from individual operations to the path level. This significantly reduces redundancy across endpoints like /checkout-sessions and /carts.
  2. Standardized Error Responses: Introduced a reusable error_response schema and added standard HTTP error responses (400, 401, 404, 500) to all operations, referencing shared definitions in components/responses.
  3. Synced with Upstream: Aligned with the latest project structure by removing legacy spec/ artifacts, ensuring a clean merge with main

These changes make the OpenAPI spec more concise, easier to read, and ensure consistent error handling documentation across the API.

Type of change

Please delete options that are not relevant.

  • Refactor (non-breaking change which improves code quality)

Is this a Breaking Change or Removal?

If you checked "Breaking change" above, or if you are removing any schema
files or fields:

  • I have added ! to my PR title (e.g., feat!: remove field).
  • I have added justification below.
## Breaking Changes / Removal Justification
N/A - This is a purely structural refactor of the source OpenAPI file.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

@oericdacosta
oericdacosta requested a review from a team January 28, 2026 21:24
@oericdacosta
oericdacosta force-pushed the refactor/openapi-dedupe-errors branch from f6454a6 to c47f76b Compare January 29, 2026 12:59
@nearlyforget
nearlyforget requested a review from jingyli February 18, 2026 19:58
@jingyli

jingyli commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

Thank you for the contribution! Some comments after going through the PR:

  1. It's a great idea to refactor out the common header parameters definition to path level to reduce duplication and make it less error prone when we add new operations.
  2. Error responses actually have been standardized since this PR is open: https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/common/types/error_response.json - so I don't think we need to do it again here.
  3. I'm not 100% convinced if we want to outline all the non-200 responses in our openapi definition. Given https://ucp.dev/latest/specification/overview/#error-handling, if we do want to specify everything, then we should make sure we include all that have been spec'ed out.

Given the file has evolved quite a bit, if you want to still keep this PR open, it'd be great to resolve the conflicts so we can take a look at the updated deltas again! Otherwise, we can close this PR and reopen a fresh one for the first point listed above.

@oericdacosta
oericdacosta force-pushed the refactor/openapi-dedupe-errors branch from c47f76b to 2fbf558 Compare June 22, 2026 20:39
@oericdacosta
oericdacosta requested review from a team as code owners June 22, 2026 20:39
@oericdacosta

Copy link
Copy Markdown
Author

@jingyli Thanks for the detailed review and feedback!

I have just rebased the branch to resolve all conflicts and updated the PR.

Following your suggestion, I have completely removed the error response standardization from this PR, as it's already being handled elsewhere. The PR is now strictly focused on the first point: deduplicating the common header parameters by moving them to the path level.

Let me know if the update look good to you!

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@oericdacosta this file seems a bit out-of-scope for the PR intent of deduplication. Please remove it from the PR

@damaz91 damaz91 added status:stale-review Applied if a PR is waiting on a reviewer for too long gov:needs-gc-review Requires review and approval from the Governance Council labels Jul 14, 2026
@damaz91 damaz91 changed the title Refactor/openapi dedupe errors refactor: openapi dedupe errors Jul 14, 2026
@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage and removed status:needs-triage Signal that the PR is ready for human triage labels Jul 14, 2026
@oericdacosta
oericdacosta force-pushed the refactor/openapi-dedupe-errors branch from c68b7ef to 584decb Compare July 18, 2026 15:43
@oericdacosta
oericdacosta force-pushed the refactor/openapi-dedupe-errors branch from 584decb to 3211c0f Compare July 18, 2026 15:45
@oericdacosta

Copy link
Copy Markdown
Author

@damaz91 Apologies for that! The cart.complete_req.json file slipped in accidentally during my local commits. I have just removed it from the branch and updated the PR. Thanks for catching that!

@gsmith85

Copy link
Copy Markdown
Contributor

Thanks for sticking with this one, @oericdacosta. You turned it around promptly every time we asked, including dropping the error-response work when @jingyli pointed at error_response.json, and pulling the stray cart.complete_req.json. Sorry this is landing as a close rather than a merge.

Two things have moved upstream since the last round that between them settle it.

The parameters this PR hoists are being deleted. #716 (open, same file) removes #/components/parameters/authorization and x_api_key entirely, replacing them with securitySchemes and a top-level security block. That is the fix for #668: declaring authentication as header parameters is invalid under OpenAPI 3.1 and ignored by most tooling. Two of the nine headers this PR relocates are on their way out, and hoisting them entrenches the pattern we are moving away from.

This file is becoming generated output. RFC #800 proposes compiling the REST binding from the JSON Schema sources via ucp-schema export-openapi, with the result committed to dist/ and guarded by --check. FR-6 of that work makes protocol header binding a compiler responsibility emitted from operations.rs. It is still in Technical Council review and the companion PR is a draft, so it is not imminent, but it is the direction of travel.

A smaller supporting point on the refactor itself. The shipped spec has 11 paths and 13 operations, and only two paths carry more than one operation (/checkout-sessions/{id} and /carts/{id}). Path-item parameters only dedupe across operations sharing a path, so hoisting the 11 universal headers takes us from 143 parameter references to 121, roughly 15%. It also does not hoist cleanly: content_digest sits on 10 of the 13 operations, so it would end up advertised on three that deliberately omit it.

Worth flagging for completeness: the June rebase looks like it resolved conflicts by taking the branch's copy of the file wholesale. The current head is missing four paths (/catalog/search, /catalog/lookup, /catalog/product, /orders/{id}), four operations and six schema bindings, and carries seven $refs that do not resolve (request_signature is referenced from every path item but defined nowhere). webhooks.orderEvent.post has also picked up operationId: lookup_catalog. That this stayed green is on us, not on you: we have VALIDATE_OPENAPI: false in linter.yaml, so nothing checks reference integrity. I am fixing that separately.

Closing this one. The discussion here is what prompted me to go measure the duplication and find the disabled linter, so it was not wasted.

If you would like to keep going, there is a better-shaped version of this same idea. Once export-openapi lands, header emission lives in operations.rs in ucp-schema, and deciding there whether common headers are emitted per-operation or per-path-item would apply uniformly across every generated profile rather than to one hand-maintained file. Happy to point you at the relevant code if that is of interest.

Thanks again for the patience across the review cycle.

@gsmith85 gsmith85 closed this Sep 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

gov:needs-gc-review Requires review and approval from the Governance Council status:stale-review Applied if a PR is waiting on a reviewer for too long

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants