Align qos-provisioning.yaml with CAMARA Commonalities r4.3

[jlurien]

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Aligns qos-provisioning.yaml with CAMARA Commonalities r4.3 (0.8.0).

Info description templates (P-026)

• Adds the three mandatory info.description template blocks with their HTML comment markers: authorization-and-authentication, additional-error-responses, and request-body-strictness (new in r4.3).
• Updates x-camara-commonalities from 0.6 to 0.8.0.

Schema $ref migration — CAMARA_common.yaml

• Replaces locally-defined Device, DeviceResponse, and ErrorInfo schemas with $ref aliases pointing to code/common/CAMARA_common.yaml.
• Replaces the x-correlator parameter and header definitions with $refs to the common file.
• Removes the now-redundant local copies of XCorrelator, NetworkAccessIdentifier, PhoneNumber, DeviceIpv4Address, SingleIpv4Address, DeviceIpv6Address, and Port.
• Replaces all Generic4xx/5xx error responses with $refs to CAMARA_common.yaml; API-specific responses (CreateAssignment400, AssignmentConflict409, CreateAssignment422) are retained locally.

Schema $ref migration — CAMARA_event_common.yaml (P-020, P-015)

• Replaces the inline CloudEvent definition with an allOf composition referencing code/common/CAMARA_event_common.yaml#/components/schemas/CloudEvent, extended with a local ApiEventType schema (single named enum, as required by P-015).
• Replaces SinkCredential and AccessTokenCredential with $ref aliases to CAMARA_event_common.yaml; adds PrivateKeyJWTCredential as a $ref alias.
• Removes PlainCredential and RefreshTokenCredential (deprecated/removed in Commonalities r4.3).

Bug fix (S-030)

• Corrects EventStatusChanged.data.required: qosStatus → status, aligning the required array with the actual property name.

Schema constraints (S-312, S-311, S-310)

• Adds maxLength: 36 to AssignmentId (UUID format).

• Adds maxLength: 2048 to BaseAssignmentInfo.sink (URI).

• Adds maxLength: 64 to AssignmentInfo.startedAt (date-time).

• Remaining S-312/S-311/S-310 warnings on migrated schemas (ErrorInfo, CloudEvent, credential types) are resolved transitively through the common-file $refs.

• Test plan updated

Which issue(s) this PR fixes:

Fixes #572

Special notes for reviewers:

• The credential model changes from {PLAIN, ACCESSTOKEN, REFRESHTOKEN} to {ACCESSTOKEN, PRIVATE_KEY_JWT} as defined in CAMARA_event_common.yaml r4.3. This is a breaking change for consumers using PLAIN or REFRESHTOKEN credential types; those types were already marked "MUST not be used" in the previous version.

Changelog input

release-note

API qos-provisioning & test plan: aligned with CAMARA Commonalities r4.3 (0.8.0)

Additional documentation

This section can be blank.

[hdamker]

Reviewed together with #579 (the sibling quality-on-demand alignment to Commonalities 0.8.0). Since both bring QoD-family APIs to r4.3 in this repo, here are the points where the two diverge — the first is worth resolving before release; the rest are suggestions to keep the two consistent:

• CloudEvent schema name collides with the common envelope. The local event subtype is named CloudEvent, the same as the CAMARA_event_common.yaml envelope it extends via allOf. When the spec is bundled, the common envelope is renamed to CloudEvent-2 to resolve the clash, which fails the PascalCase naming rule. The PR validation lints the source so it stays green, but the release review runs against the bundled spec and will flag it — so best resolved before then. Suggest a domain-specific subtype name (as Align quality-on-demand API and tests with Commonalities 0.8.0 (r4.3) #579 uses QosNotificationEvent) and likewise ApiEventType → e.g. QosProvisioningEventType.
• identifying-device-from-access-token template block is missing. The section text is present but not wrapped in the mandatory r4.3 info.description marker (see code/common/info-description-templates.yaml); Align quality-on-demand API and tests with Commonalities 0.8.0 (r4.3) #579 includes it.
• PRIVATE_KEY_JWT depth. It's enabled in the credential enum, but there's no PRIVATE_KEY_JWT_NOT_CONFIGURED (422) response or prose on the allowed credentialType values. Align quality-on-demand API and tests with Commonalities 0.8.0 (r4.3) #579 adds both — worth matching, or confirming it's intentionally out of scope here.
• 403 codes. This references the common Generic403 (PERMISSION_DENIED + INVALID_TOKEN_CONTEXT); Align quality-on-demand API and tests with Commonalities 0.8.0 (r4.3) #579 restricts 403 to PERMISSION_DENIED only. Worth a consistent choice across the two APIs.
• Component reuse (broader). This PR keeps the full component set local — common schemas re-exposed as local $ref aliases (a few, like AccessTokenCredential / PrivateKeyJWTCredential, end up unreferenced), and openId / notificationsBearerAuth kept inline — with use-sites pointing at the local names; Align quality-on-demand API and tests with Commonalities 0.8.0 (r4.3) #579 references the common components directly at each use-site. Either style works, but aligning on one across both APIs keeps the repo consistent.

Happy to reconcile alternatively in #579 once we agreed on the direction.

[hdamker]

@camaraproject/quality-on-demand_codeowners do we know when @jlurien will be back to address the remaining points of this PR? I can offer to take the points and address them with dedicated commits.

Regarding the "component reuse" we had agreed to reference the common file already at each use occurrence, not via a local proxy component, right?

[jlurien]

@hdamker Thanks for the detailed review

Already addressed in recent commits on this branch:

Issue 3 — PRIVATE_KEY_JWT depth: PRIVATE_KEY_JWT_NOT_CONFIGURED is now documented in the createAssignment 422 response (with a named example), and the info.description prose clarifies that sinkCredential.credentialType MUST be ACCESSTOKEN or PRIVATE_KEY_JWT.
Issue 4 — 403 codes: The spec uses a local PermissionDenied403 restricted to PERMISSION_DENIED only, matching the pattern used in the merged #579.

Being addressed now:

Issue 1 — CloudEvent naming (blocker): Renaming the local event container schema from CloudEvent to QosProvisioningNotificationEvent, and ApiEventType to QosProvisioningEventType, to eliminate the bundler collision.
Issue 2 — identifying-device-from-access-token markers: Adding the mandatory wrappers, aligning the template content verbatim and keeping the API-specific QOS_PROVISIONING.QOS_PROFILE_NOT_APPLICABLE bullet after the END marker.
Issue 5 — Component reuse: Removing all local proxy aliases for Device, DeviceResponse, ErrorInfo, and SinkCredential from components/schemas, and updating each use-site to reference the common file directly. Also removing the two unreferenced aliases (AccessTokenCredential, PrivateKeyJWTCredential).

[hdamker]

Being addressed now

@jlurien if you like you can use the commits in jlurien#2 if they fit.

[jlurien]

Sorry, I did not pushed the commit

[hdamker]

@jlurien the PR looks good to me now. Below I suggested the four blank line to enable correct rendering in swagger. Beyond that I recognized that you kept some "proxy" components locally, e.g. x-correlator header and parameter which are also defined in CAMARA_common.yaml. That could be intentional, especially to keep local and common error responses in one place, so nothing what I suggest here.

[jlurien]

@hdamker, addressed your remaining suggestions from the 2026-07-24 review:

All local-proxy components have been removed. Every use-site in qos-provisioning.yaml now references the canonical common files directly:

• securitySchemes.openId → $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId"
• securitySchemes.notificationsBearerAuth → $ref: "../common/CAMARA_event_common.yaml#/components/securitySchemes/notificationsBearerAuth"
• x-correlator parameter and header: all 13 use-sites updated to reference CAMARA_common.yaml directly; the parameters.x-correlator, headers.x-correlator, and the entire headers: subsection removed from components.
• Generic400/401/410/422/429: all 17 response use-sites updated to reference CAMARA_common.yaml directly; the 5 thin-proxy response definitions removed.

API-specific responses (CreateAssignment400, PermissionDenied403, NotFound404, AssignmentConflict409, CreateAssignment422) and all local schemas are unchanged.

[hdamker]

LGTM, thanks @jlurien. I also checked the bundled spec: no name collisions left, and the x-correlator parameter and header resolve to a single local component each.

[hdamker]

@RandyLevensalor @eric-murray would you (re-)review and approve as well?

[RandyLevensalor]

LGTM