Comprehensive Pull Request for Issues Identified during Release Review

[gmuratk]

What type of PR is this?

Add one of the following kinds:

• correction
• enhancement/feature
• cleanup
• documentation

What this PR does / why we need it:

Release review identified many issues including documentation, cleanup, and enhancements.

Which issue(s) this PR fixes:

Fixes #114, #131, #133, #134, #135, #136, #137, #112, #121

Special notes for reviewers:

Partially addresses issue #132 (documentation changed, but YAML changes are deferred)

Changelog input

 release-note
- [QOS B&A] **[BREAKING]** Renamed `Status` enum to `AssignmentStatus` and restricted its scope to device assignment/release operations only. `AssignmentStatus` replaces the overloaded use of `Status` in assignment outcomes (#114).
- [QOS B&A] **[BREAKING]** Renamed `StatusChanged` enum to `AssignmentStatusChanged` for scope and naming clarity in assignment notifications (#114).
- [QOS B&A] **[BREAKING]** Introduced new `BookingStatus` enum (`REQUESTED | SCHEDULED | ACTIVE | TERMINATED`) to explicitly model the booking lifecycle. Replaces implicit lifecycle state inference from `status + statusInfo` pattern (#114).
- [QOS B&A] **[BREAKING]** Introduced new `BookingStatusChanged` enum for booking status-change notifications (`SCHEDULED | ACTIVE | TERMINATED`). Excludes `REQUESTED` as notifications only fire on confirmed or terminal states (#114).
- [QOS B&A] **[BREAKING]** Renamed `BookingOutput.status` field to `bookingStatus` (type: `BookingStatus`, required). Field is required, eliminating the need to check optional `statusInfo` for lifecycle state (#114).
- [QOS B&A] **[BREAKING]** Renamed `DeviceAssignmentOutput.status` field to `assignmentStatus` (type: `AssignmentStatus`). Provides symmetry with `bookingStatus` in booking responses (#114).
- [QOS B&A] **[BREAKING]** Renamed event type from `org.camaraproject.qos-booking-and-assignment.v0.status-changed` to `org.camaraproject.qos-booking-and-assignment.v0.booking-status-changed`. Updated `QosBookingNotificationEvent` discriminator mapping accordingly (#114).
- [QOS B&A] **[BREAKING]** Updated `EventBookingStatusChanged.data.status` field to `bookingStatus` (type: `BookingStatusChanged`) for naming consistency (#114).
- [QOS B&A] **[BREAKING]** Updated `EventAssignmentStatusChanged.data.status` field to `assignmentStatus` (type: `AssignmentStatusChanged`) for symmetry with booking events (#114).
- [QOS B&A] **[BREAKING]** Converted `BookingStatusInfo` from closed enum to free-form string (`type: string, maxLength: 256`). Lifecycle values are now states in `BookingStatus`; terminal reasons (e.g., `BOOKING_CANCELLED`, `BOOKING_EXPIRED`, `SERVICE_NOT_AVAILABLE`) are now `statusInfo` values under `TERMINATED` state (#114).
- [QOS B&A] **[BREAKING]** Converted `AssignmentStatusInfo` from closed enum to free-form string (`type: string, maxLength: 256`). Added `DEVICE_RELEASED` to support the new `RELEASED` assignment status. Allows operator-specific reasons (#114).
- [QOS B&A] **[BREAKING]** Added new `AssignmentStatus` value: `RELEASED` (device(s) released from booking) (#114).
- [QOS B&A] **[BREAKING]** Added new `AssignmentStatusChanged` value: `RELEASED`. Enables unambiguous 
  discrimination of release operation outcomes in async callbacks (#114).
- [QOS B&A] Added new `BookingDetails.bookingStatus` field (optional, type: `BookingStatus`). Allows embedded booking snapshots in `DeviceAssignmentOutput` to carry lifecycle state without mixing it into the assignment's own `assignmentStatus` (#114).
- [QOS B&A] Updated all examples to reflect renamed fields and new status enums:1 `BOOKING_PENDING` example: now includes `bookingId`, uses `bookingStatus: REQUESTED`, `bookingDeviceCount: 5` (#134). 2 `BOOKING_SUCCESSFUL` example: now uses `bookingStatus: SCHEDULED`, `statusInfo: BOOKING_SCHEDULED` (deprecated `BOOKING_ACCEPTED`) (#114). 3. All device assignment examples: updated to use `assignmentStatus` instead of `status` (#114).
- [QOS B&A] **[BREAKING]** Renamed `AssignmentStatus.PENDING` to `REQUESTED` for naming alignment with `BookingStatus.REQUESTED`; both now convey "your request was accepted, confirmation to follow." Applied throughout the enum, `assignDevices` operation description, `ASSIGNMENT_PENDING` and `ASSIGNMENT_RELEASE_PENDING` example payloads (#114).
- [QOS B&A] **[BREAKING]** Renamed `AssignmentStatus.SUCCESSFUL` to `ASSIGNED`. `ASSIGNED` names the device state achieved (devices are assigned to the booking) rather than an operation outcome, consistent with `RELEASED`. Applied throughout the enum, `AssignmentStatusChanged`, all operation descriptions, and `ASSIGNMENT_SUCCESSFUL`, `ASSIGNMENT_RETRIEVED_1`, `ASSIGNMENT_RETRIEVED_2` example payloads (#114).
- [QOS B&A] **[BREAKING]** Renamed `BookingInput.numDevices` and `BookingOutput.totalDevices` to `bookingDeviceCount` for consistency. `bookingDeviceCount` now used uniformly across input, output, and embedded booking details (#133).
- [QOS B&A] **[BREAKING]** `createBooking` now returns HTTP `201 Created` for all booking outcomes (`REQUESTED`, `SCHEDULED`, `ACTIVE`, `TERMINATED`). HTTP `202 Accepted` removed. A `bookingId` is immediately returned and accessible. (RFC 7231 §6.3.2) (#134).
- [QOS B&A] **[BREAKING]** `deleteBooking` now returns HTTP `204 No Content` on synchronous success (no response body), per CAMARA API Design Guide §5.7.6. HTTP `200` with body removed (#135).  
- [QOS B&A] **[BREAKING]** `BOOKING_CANCELLED` example repurposed from `deleteBooking` 200 response body to a `booking-status-changed` notification payload example (`bookingStatus: TERMINATED`, `statusInfo: BOOKING_CANCELLED`). The terminal cancellation state is now only observable via the CloudEvent notification or a subsequent `GET`. Aligns with change to `204 No Content` on synchronous delete success (#135).
- [QOS B&A] Expanded `deleteBooking` operation description to document: 1. Provider-specific behavior when assigned devices exist (auto-release vs `409 INCOMPATIBLE_STATE`)  2. CloudEvent delivery semantics for async cancellation (#136).
- [QOS B&A] Updated `ASSIGNMENT_RELEASED` example to use `assignmentStatus: RELEASED`, `statusInfo: DEVICE_RELEASED`. Previous example incorrectly returned `assignmentStatus: SUCCESSFUL` for a release completion (#137).
- [QOS B&A] Fixed S-211 validation warning: `BOOKING_FAILURE` example is now referenced from the `createBooking` 201 response examples block (alongside `BOOKING_SUCCESSFUL` and `BOOKING_PENDING`), resolving the "potentially unused component" warning (#112, #121).
- [QOS B&A] Fixed CAMARA mandatory section formatting in `info.description`: added missing blank lines after `BEGIN` markers for `authorization-and-authentication`, `additional-error-responses`, and `request-body-strictness`; wrapped the `identifying-device-from-access-token` section in `CAMARA:MANDATORY:identifying-device-from-access-token:BEGIN/END` markers; corrected `additional-error-responses` body text to reference the `x-camara-commonalities` field in place of the deprecated `API Readiness Checklist` reference (#131).
- [QOS B&A] Removed hardcoded API version reference (`v0.1`) from `info.description`; replaced with a version-neutral capability statement (#131).
- [QOS B&A] Added `# Booking and assignment lifecycle` section to `info.description` with ASCII state diagrams, state-transition tables, and notification event mapping for both the booking lifecycle (`REQUESTED → SCHEDULED → ACTIVE → TERMINATED`) and the device assignment  lifecycle (`REQUESTED → ASSIGNED | RELEASED | PARTIAL_SUCCESS | FAILURE`). Includes sync/async/hybrid operator note and notification delivery table (#131).
- [QOS B&A] Added `# API-specific error behaviour` section to `info.description` documenting 400/409 code scope and 422 applicability per operation. Corrects three implicit spec defects: `404` removed from `createBooking` (no path parameter); `404` and `409` removed from `retrieveBookingByDevice` (read operation returns empty array on no match); `422` removed from `getDevicesByBookingId` (no device object in request body) (#131).
- [QOS B&A] Added `# Three-legged access token restrictions` section to `info.description` documenting two-legged vs three-legged token usage, `device`/`devices` field restrictions, and the optional operator B2B2C multi-device self-service pattern (#131).

Additional documentation

This section can be blank.

docs

[Masa8106]

Hi @gmuratk, thank you so much for your prompt actions.
Do you need to include these changes into r2.1 (#119)? If no, I prefer that these changes are defered to the next version, r2.2, as I mentioned in the meeting today.
Of course, I will review these changes shortly. Thank you.

[gmuratk]

Hi @Masa8106, they can be deferred to next version.