feat(ipa): add IPA-132 OperationResponse schema rules - #1437
Open
julius-jogela wants to merge 4 commits into
Open
feat(ipa): add IPA-132 OperationResponse schema rules#1437julius-jogela wants to merge 4 commits into
julius-jogela wants to merge 4 commits into
Conversation
julius-jogela
force-pushed
the
feat-ipa-132-operation-response-schema
branch
2 times, most recently
from
August 14, 2026 16:20
0dd2c21 to
ed56aed
Compare
Add the three rules validating how long-running operation status is communicated through the OperationResponse schema: - xgen-IPA-132-operation-endpoints-must-return-operation-response: the single Operation endpoint must reference the OperationResponse schema, and the Operations collection endpoint must return a paginated response whose results reference it. - xgen-IPA-132-operation-status-must-use-the-standard-status-enum: the schema must report progress through a status field using exactly the enum PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED, SUPERSEDED. - xgen-IPA-132-operation-response-must-include-core-metadata: operationId, operationType, createdAt and updatedAt must be defined and required, operationType must use exactly the enum CREATE, UPDATE, DELETE, CUSTOM, and customMethod must be defined but not required. The schema name, both enums and the exact-enum-match helper live in utils/longRunningOperations.js for reuse by the remaining IPA-132 rules.
julius-jogela
force-pushed
the
feat-ipa-132-operation-response-schema
branch
from
August 14, 2026 17:18
10a7ed2 to
14859d3
Compare
julius-jogela
marked this pull request as ready for review
August 17, 2026 09:37
julius-jogela
requested review from
andreaangiolillo,
chrysanthi-m,
drinkbird,
maks-m-mongo-leaf,
saisundar,
wtrocki and
yelizhenden-mdb
August 17, 2026 09:37
Per review of the IPA-132 guideline examples, the status field must be listed as required: an OperationResponse that can legally omit status defeats polling. The status enum rule now checks required membership in addition to the exact enum, matching the updated guideline example.
Per review, the test fixtures follow the same pattern across the IPA-132 test files: the operations and schemas under test are defined once at the top of the file and reused across the test cases.
Address findings from a deeper review of the OperationResponse rules: - The status enum and core metadata rules read properties and required lists through allOf sub-schemas, which Spectral does not flatten, so an allOf-composed OperationResponse no longer produces false violations. - The Operations collection endpoint must reference a paginated wrapper schema: inline wrappers are rejected, consistent with xgen-IPA-110-collections-use-paginated-prefix, which rejects them at error severity. The results property of the wrapper may live in one of its allOf sub-schemas. - The single Operation endpoint no longer accepts an array schema whose items reference OperationResponse. - The endpoint rule checks its cheap path and media type gates before walking the document.
| }, | ||
| }, | ||
| // A paginated wrapper composed with allOf, which Spectral does not flatten | ||
| PaginatedAllOfOperationResponse: { |
Collaborator
There was a problem hiding this comment.
Why do we allow allOf? Could you clarify that?
| type: 'object', | ||
| required: ['operationId', 'operationType', 'createdAt', 'updatedAt'], | ||
| properties: { | ||
| operationId: { type: 'string' }, |
Collaborator
There was a problem hiding this comment.
Looking at the Technical Design document, I see that there are other required fields, in other words, core metadata. Shouldn't they be involved here as well?
|
|
||
| message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-132-operation-response-must-include-core-metadata' | ||
| severity: warn | ||
| given: $.components.schemas.OperationResponse |
Collaborator
There was a problem hiding this comment.
Can you define an alias for it and re-use later?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed changes
This PR adds the IPA-132 rules validating how long-running operation status is communicated through the
OperationResponseschema. Stacked on #1435; the base retargets tomainonce that merges.Jira ticket: CLOUDP-429837
Rules added
All at
warnseverity:xgen-IPA-132-operation-endpoints-must-return-operation-responseIPA-132-operation-endpoints-must-return-operation-response.../operations/{operationId}) must reference theOperationResponseschema; the Operations collection endpoint must return a paginated response whoseresultsitems reference it. Exceptions at the content media type levelxgen-IPA-132-operation-status-must-use-the-standard-status-enumIPA-132-operation-status-must-use-the-standard-status-enumOperationResponsemust define astatusproperty whose enum is exactlyPENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED,SUPERSEDEDxgen-IPA-132-operation-response-must-include-core-metadataIPA-132-operation-response-must-include-core-metadataoperationId,operationType,createdAt,updatedAtdefined and required;operationTypeenum exactlyCREATE,UPDATE,DELETE,CUSTOM;customMethoddefined but not required (it applies only toCUSTOMoperations, which cannot be validated statically)The schema rules anchor on
$.components.schemas.OperationResponseper the guideline metadata. TheOperationResponseschema name, both enums and the exact-enum-match helper live inutils/longRunningOperations.jsfor reuse by the remaining IPA-132 rules.Testing
gen-ipa-docs, prettier and eslint clean.spectral lint openapi/.raw/v2.yamlwith the full ruleset: 0xgen-IPA-132-*findings — the spec defines noOperationResponseschema yet.required, and de-referencing the schemas each fires exactly the right rule.Checklist
Changes to Spectral