diid

Appearance

Breaking Change Detection & Approvals ​

diid inspects uploaded API specifications to identify contract changes and prevent unintended service disruptions.

Change Severity ​

Changes are grouped into two categories:

  • Non-Breaking (Warnings): Additions such as new endpoints, optional fields, or deprecation tags. These do not require approval.
  • Breaking (Errors): Incompatible changes to existing endpoints, parameters, or schemas that affect existing clients. These require approval from downstream consumers.

Common Breaking Changes ​

  • OpenAPI: Removing paths or HTTP methods, adding required fields, changing property data types, or tightening validation constraints.
  • AsyncAPI: Deleting channels, modifying message operation definitions, or altering message payload schemas.
  • GraphQL: Removing object types, deleting fields, or changing input/output field types.
  • SOAP/WSDL: Removing operations or modifying XML Schema Definition (XSD) types.

Spec Version Lifecycle ​

Specifications progress through a defined lifecycle based on breaking change analysis:

  1. Draft: Initial ingested version undergoing parsing and contract diff analysis.
  2. Current (Published): The active, deployed specification in production (status: "published", is_current: true). Only one Current version can exist at a time per project. When changes are non-breaking (e.g., additions, deprecations), the draft is published directly to Current.
  3. Future (Pending Approval): A proposed release candidate containing breaking changes (is_future: true, status: "pending_approval"). Only one Future version can exist at a time. The producer cannot deploy this candidate until all impacted downstream consumers grant approval.
  4. Version History: When a new version is deployed to Current, the previous Current version is superseded (status: "published", is_current: false) and preserved in Version History for auditing, rollbacks, and visual diffs.
  5. Discarded: If breaking changes are abandoned or need rework, project admins can cancel advancement, deleting the Future candidate and leaving the Current version unaffected.

Approval Workflow ​

When a specification update contains breaking changes:

  1. Selective Consumer Scope: diid identifies consumer projects depending on the producer. If a consumer selected specific endpoints or channels, approvals are only required if those selected endpoints are affected. Consumers with broad dependencies receive approval requests for all breaking changes.
  2. Deployment Gate: The producer project is blocked from promoting the spec to Current until every impacted consumer project approves the changes. The release candidate remains in the Future state.
  3. Reviewing Diffs: Consumer admins review side-by-side visual diffs highlighting modified endpoints, parameters, and schema constraints, with changes color-coded and formatted.
  4. Bidirectional Notifications:
    • Impacted consumer teams receive alerts with direct links to review and approve the diffs.
    • Producer teams receive visibility into affected consumers, breaking change counts, and real-time approval progress.
  5. Promotion or Cancellation:
    • Once all approvals are received, the Future version enters the Ready state, allowing producer admins to click Deploy to promote it to Current.
    • Producers can click Cancel at any time to purge the Future candidate and abandon the proposed update.