I'll run the breaking-change check on the two specs and write the full artifact set. ## API Contract Diff — 1.0.0 → 2.0.0 Engine: manual-read (no oasdiff run; I compared the specs by hand) Base: base-v1.yaml (v1.0.0) New: new-v2.yaml (v2.0.0) ### Summary | Severity | Count | Notes | |----------|-------|-------| | `ERR` | 3 | removed endpoint, new required field, removed response field | | `WARN` | 0 | none | | `INFO` | 1 | version bump 1.0.0 → 2.0.0 | **Exit code: 1** — 3 breaking changes detected. ### Breaking changes (`ERR`) - **ERR-001:** `GET /users/{id}` was deleted. *Fix:* restore it, or deprecate it with a sunset date first. - **ERR-002:** `POST /users` now requires `phone`, so existing clients sending only `name` and `email` will be rejected. *Fix:* make `phone` optional or default it server-side. - **ERR-003:** `User.email` was removed from the response schema, which breaks `GET /users` clients that read it. *Fix:* keep `email` (optionally `deprecated: true`), or add a separate `UserV2` schema. ### Warnings (`WARN`) none ### Info (`INFO`) - `info.version` changed from 1.0.0 to 2.0.0. ### Unchanged - `GET /users` operation, 200 status and array-of-User shape. Its payload is affected by ERR-003. - `POST /users` 201 response and the `name` and `email` request fields. - `User.id` and `User.name`. ### ERR checklist | Category | Result | |----------|--------| | Deleted endpoint | **fail** | | Modified path parameter | pass (the only path parameter belonged to the deleted endpoint, already ERR-001) | | Status code shift | pass (on retained operations) | | Removed response field | **fail** | | New required request field | **fail** | | Type narrowing | pass | | Enum value removal | pass | ### Artifacts - `API_CHANGELOG.md` - `BREAKING_CHANGES.md` - `diff.json` - `DEPRECATION_PLAN.md` was not emitted. The skill requires it only for a `WARN` deprecation or an approved `ERR` change, and neither exists here. If you approve these changes as intentional, it becomes mandatory and I can generate it. Sources: none (analysis based on the attached SKILL.md and the two specs) { "schema_version": "1.0", "engine": "manual-read", "base": { "path": "base-v1.yaml", "version": "1.0.0" }, "new": { "path": "new-v2.yaml", "version": "2.0.0" }, "summary": { "err": 3, "warn": 0, "info": 1 }, "exit_code": 1, "breaking": [ { "id": "ERR-001", "rule": "removed-endpoint", "location": "GET /users/{id}", "description": "The path /users/{id} and its GET operation were removed. Clients fetching a single user will receive 404/405.", "remediation": "Restore GET /users/{id}, or keep it and mark it deprecated with a sunset date before removing it in a later major version." }, { "id": "ERR-002", "rule": "new-required-field", "location": "POST /users", "field": "requestBody.phone", "description": "New required request field 'phone' was added. Existing clients that send only name and email will be rejected.", "remediation": "Make 'phone' optional (remove it from 'required'), or apply a server-side default, until clients have migrated." }, { "id": "ERR-003", "rule": "removed-response-field", "location": "GET /users (200)", "field": "components.schemas.User.email", "description": "Property 'email' was removed from the User schema, which is returned by GET /users (items). Clients reading 'email' will break. The same removal affected the deleted GET /users/{id}.", "remediation": "Keep 'email' in User (optionally mark deprecated: true), or introduce a new schema/version (e.g. UserV2) and keep User unchanged for v1 clients." } ], "warnings": [], "info": [ { "id": "INFO-001", "rule": "metadata-change", "location": "info.version", "description": "API version changed from 1.0.0 to 2.0.0." } ], "unchanged": [ "GET /users (operation, 200 status code, array-of-User response shape)", "POST /users (201 response, request fields name and email)", "components.schemas.User.id", "components.schemas.User.name" ], "err_checklist": { "deleted_endpoint": "fail", "modified_path_parameter": "pass", "status_code_shift": "pass", "removed_response_field": "fail", "new_required_request_field": "fail", "type_narrowing": "pass", "enum_value_removal": "pass" } } # Breaking Changes — User Service API 1.0.0 → 2.0.0 Engine: manual-read Exit code: 1 — 3 `ERR` findings detected. ## ERR-001 — Removed endpoint: `GET /users/{id}` The path `/users/{id}` no longer exists. Any client fetching a single user will fail. **Remediation** - Restore `GET /users/{id}` in v2, or - Keep it, mark `deprecated: true`, publish a sunset date, and remove it in a later major version (see api-versioning-strategy). ## ERR-002 — New required request field: `POST /users` → `phone` `phone` was added to the request body `required` list. Existing clients send only `name` and `email` and will be rejected. **Remediation** - Make `phone` optional (drop it from `required`), or - Default it server-side until clients migrate, then enforce it in a future major version. ## ERR-003 — Removed response field: `User.email` `email` was removed from `components.schemas.User`, which is returned in `GET /users` items (and previously `GET /users/{id}`). Clients reading `email` will break. **Remediation** - Restore `email` on `User` (optionally `deprecated: true`), or - Introduce a separate `UserV2` schema and keep `User` unchanged for existing clients. # API Changelog — User Service API 1.0.0 → 2.0.0 Engine: manual-read | Severity | Count | Notes | |----------|-------|-------| | `ERR` | 3 | removed endpoint, new required field, removed response field | | `WARN` | 0 | none | | `INFO` | 1 | version bump | Exit code: 1 — breaking changes detected. ## ERR ### `GET /users/{id}` - **ERR-001** Endpoint removed. ### `POST /users` - **ERR-002** Request field `phone` added and marked required. ### `GET /users` - **ERR-003** Response schema `User` lost property `email`. ## WARN none ## INFO ### Metadata - **INFO-001** `info.version` 1.0.0 → 2.0.0. ## Unchanged - `GET /users` operation, 200 status, array-of-User shape - `POST /users` 201 response; request fields `name`, `email` - `User.id`, `User.name`