Skip to content

feat(ipa): add IPA-132 OperationResponse schema rules - #1437

Draft
julius-jogela wants to merge 1 commit into
feat-ipa-132-operations-resource-rulesfrom
feat-ipa-132-operation-response-schema
Draft

feat(ipa): add IPA-132 OperationResponse schema rules#1437
julius-jogela wants to merge 1 commit into
feat-ipa-132-operations-resource-rulesfrom
feat-ipa-132-operation-response-schema

Conversation

@julius-jogela

Copy link
Copy Markdown
Collaborator

Proposed changes

This PR adds the IPA-132 rules validating how long-running operation status is communicated through the OperationResponse schema. Stacked on #1435; the base retargets to main once that merges.

Jira ticket: CLOUDP-429837

Rules added

All at warn severity:

Rule Guideline Checks
xgen-IPA-132-operation-endpoints-must-return-operation-response IPA-132-operation-endpoints-must-return-operation-response The single Operation endpoint (.../operations/{operationId}) must reference the OperationResponse schema; the Operations collection endpoint must return a paginated response whose results items reference it. Exceptions at the content media type level
xgen-IPA-132-operation-status-must-use-the-standard-status-enum IPA-132-operation-status-must-use-the-standard-status-enum OperationResponse must define a status property whose enum is exactly PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED, SUPERSEDED
xgen-IPA-132-operation-response-must-include-core-metadata IPA-132-operation-response-must-include-core-metadata operationId, operationType, createdAt, updatedAt defined and required; operationType enum exactly CREATE, UPDATE, DELETE, CUSTOM; customMethod defined but not required (it applies only to CUSTOM operations, which cannot be validated statically)

The schema rules anchor on $.components.schemas.OperationResponse per the guideline metadata. The OperationResponse schema name, both enums and the exact-enum-match helper live in utils/longRunningOperations.js for reuse by the remaining IPA-132 rules.

Testing

  • 25 new tests: every Correct/Incorrect example from the IPA-132 guidelines is a test case, plus per rule a violation-with-exception (suppressed) and adoption-with-exception (flagged as unnecessary) case, and unit tests for the enum helper.
  • Full suite: 122 suites / 758 tests pass. gen-ipa-docs, prettier and eslint clean.
  • spectral lint openapi/.raw/v2.yaml with the full ruleset: 0 xgen-IPA-132-* findings — the spec defines no OperationResponse schema yet.
  • Live-fire check: a complete compliant LRO spec produces 0 findings across all six IPA-132 rules; planting a non-standard enum value, dropping a field from required, and de-referencing the schemas each fires exactly the right rule.

Checklist

  • I have signed the MongoDB CLA
  • I have added tests that prove my fix is effective or that my feature works

Changes to Spectral

  • I have read the README file for Spectral Updates

@julius-jogela
julius-jogela force-pushed the feat-ipa-132-operation-response-schema branch 2 times, most recently from 0dd2c21 to ed56aed Compare August 14, 2026 16:20
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
julius-jogela force-pushed the feat-ipa-132-operation-response-schema branch from 10a7ed2 to 14859d3 Compare August 14, 2026 17:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant