Skip to content

Align qos-booking-and-assignment booking status model with the lifecycle model agreed for qos-booking #114

Description

@hdamker

Problem description
The two APIs in this repository model the status of a booking with incompatible state machines:

  • qos-booking uses a lifecycle model, deliberately agreed in QoS B: Update the status diagram #83 / QoS B: Update the booking status #88 to align with the other CQM APIs: BookingStatus = REQUESTED / SCHEDULED / ACTIVATED / TERMINATED, with transition reasons in statusInfo (final state diagram: QoS B: Update the booking status #88 (comment)). Dedicated Networks uses the same lifecycle shape (NetworkStatus = REQUESTED / RESERVED / ACTIVATED / TERMINATED, dedicated-network.yaml).
  • qos-booking-and-assignment uses a single operation-outcome enum Status = PENDING / SUCCESSFUL / PARTIAL_SUCCESS / FAILURE for two different questions: "did my assign/release request complete?" (where it fits well — PARTIAL_SUCCESS for "7 of 10 devices assigned" is genuinely an operation outcome) and "where is my booking in its life?" (where it doesn't — lifecycle information is instead smuggled into the optional statusInfo values BOOKING_ACCEPTED, BOOKING_ACTIVATED, BOOKING_EXPIRED, BOOKING_CANCELLED).

Because statusInfo is optional, a qos-booking-and-assignment consumer cannot reliably distinguish "confirmed, waiting for the start time" from "active right now" — both are status: SUCCESSFUL. That is a functional gap, not only a style mismatch. The Use-Case driven API function concept comparison maps all three booking-family APIs onto the same lifecycle phases and shows qos-booking-and-assignment as the outlier.

Notably, the API's own event model already anticipates the separation — it defines two event types (…v0.status-changed for the booking, …v0.assignment-status-changed for assignments) — but feeds both from the same outcome enum.

Possible evolution
Complete the split that the event model already implies, and align the booking resource with the model agreed in #88:

  • BookingOutput / BookingDetails: replace status with bookingStatus = REQUESTED / SCHEDULED / ACTIVATED / TERMINATED (identical to qos-booking), and reduce BookingStatusInfo to transition reasons (SERVICE_NOT_AVAILABLE, QOS_PROFILE_NOT_SUPPORTED, DELETE_REQUESTED, DURATION_EXPIRED, NETWORK_TERMINATED, …). The lifecycle values disappear from statusInfo because they become states. A declined booking follows the qos-booking pattern (bookingStatus: TERMINATED with a decline reason) instead of FAILURE without a bookingId.
  • DeviceAssignmentOutput: keep PENDING / SUCCESSFUL / PARTIAL_SUCCESS / FAILURE for the assign/release operations (optionally renamed to assignmentStatus to make the distinction explicit).
  • Events: status-changed carries booking lifecycle transitions (as in qos-booking), assignment-status-changed keeps operation outcomes.
  • The privacy/data-minimization principles agreed in QoS B: Update the booking status #88 apply here as well: one lifecycle status on the booking, reasons in statusInfo, no availability sub-states that would expose device location.
  • For the confirmed-before-start state this proposal uses SCHEDULED for consistency within the repository; the SCHEDULED vs RESERVED naming difference towards Dedicated Networks is a cross-repository question that should go to the CQM alignment discussion rather than being settled here.

Alternative solution
If there are known implementations of qos-booking-and-assignment 0.x that need a migration path, the same end state could be reached in two steps (add bookingStatus alongside the existing status first, remove the overloaded use in a later version).

Additional context
Found while reviewing #109 (release review r2.1). Timing is up to the team: the mismatch could be accepted for the 0.2.0 versions of both APIs and addressed in the next minor version, or changed in an rc.2 already.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions