Skip to content

Sync Commonalities to r4.4 (0.9.0) - #86

Merged
JoseMConde merged 10 commits into
camaraproject:mainfrom
DLondonoD:comm-r4.4
Sep 28, 2026
Merged

JoseMConde merged 10 commits into
camaraproject:mainfrom
DLondonoD:comm-r4.4

Conversation

@DLondonoD

Copy link
Copy Markdown
Contributor

What type of PR is this?

  • enhancement/feature

What this PR does / why we need it:

Bumps this API's Commonalities target from r4.3 (0.8.0) to r4.4 (0.9.0) and adopts the resulting Design Guide changes:

  • Resynced code/common/CAMARA_common.yaml, CAMARA_event_common.yaml and info-description-templates.yaml to their r4.4 content, updating .sync-manifest.yaml with the corresponding blob hashes, and bumped info.x-camara-commonalities to 0.9.0.
  • Updated the mandatory "Additional CAMARA error responses" info.description text to r4.4's wording (points to x-camara-commonalities/changelog/release metadata instead of the removed "API Readiness Checklist" document reference).
  • Replaced every $ref to the deprecated Generic400/401/403/404 responses with the new named catalogue from CAMARA_common.yaml (BadRequest400, Unauthenticated401, PermissionDenied403, NotFound404), and removed this API's local Generic400/403/404 overrides, which existed only to work around a P-040 bundling name collision that no longer applies.
  • Migrated locally-defined 409 responses (ALREADY_EXISTS/INCOMPATIBLE_STATE) to the CAMARA_common.yaml Track-2 template (ErrorInfo allOf'd with a local status/code enum restriction), matching the r4.4 Design Guide's required pattern for locally-defined error responses.
  • SubscriptionRequest.sink now $refs the shared Sink schema in CAMARA_event_common.yaml instead of duplicating its string/format/pattern/maxLength definition locally.
  • SinkCredential now allOf's the common AccessTokenCredential and locally restricts credentialType to ACCESSTOKEN only (PRIVATE_KEY_JWT, newly supported by Commonalities r4.4, is intentionally not offered by this API); the local AccessTokenCredential schema was removed as it's no longer needed.
  • Added the new 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED response (components/responses/EventNotificationsNotSupported422) to both createAppInstance and createAppDeployment, documenting that providing subscriptionRequest.sink when the Edge Cloud Platform cannot deliver notifications results in this error without creating the resource.
  • Added additionalProperties: false to every request body schema (and inline request body) with no composition at its own top level, per the r4.4 Design Guide's Appendix B strictness guidance.
  • Reformatted enum descriptions with per-value meaning into markdown bullet lists, per Appendix B.3.

Which issue(s) this PR fixes:

Fixes #

Special notes for reviewers:

Not addressed in this PR (tracked separately):

  • Local duplication of SinkCredential/AccessTokenCredential/sink/SubscriptionConfig against the r4.4 CAMARA_event_common.yaml equivalents (Sink, SinkCredential w/ PRIVATE_KEY_JWT, ConfigBase) is only partially resolved here.
  • Echoing sink back in AppInstanceInfo/AppDeploymentInfo on success, as newly recommended by the Guide, is a separate schema change and is not part of this PR.
  • AppManifest is deliberately excluded from the additionalProperties: false change: it's allOf'd into AppManifestInfo (adding the appId property), and restricting it directly would make that allOf combination invalid under standard JSON Schema semantics.

Changelog input

release-note
Sync Commonalities to r4.4 (0.9.0): adopt the shared named error response catalogue, Track-2 pattern for local error responses, shared Sink/AccessTokenCredential schemas, the new 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED response, additionalProperties: false on request bodies, and bullet-list enum descriptions.

Additional documentation

docs

Bumps this API's Commonalities target from r4.3 (0.8.0) to r4.4
(0.9.0):

- Resynced code/common/CAMARA_common.yaml, CAMARA_event_common.yaml
  and info-description-templates.yaml to their r4.4 content, updating
  .sync-manifest.yaml with the corresponding blob hashes.
- Bumped info.x-camara-commonalities to 0.9.0.
- Updated the "Additional CAMARA error responses" mandatory
  info.description text to r4.4's wording (points to
  x-camara-commonalities/changelog/release metadata instead of the
  removed "API Readiness Checklist" document reference).
- Replaced every $ref to the deprecated Generic400/401/403/404
  responses with the new named catalogue from CAMARA_common.yaml:
  BadRequest400, Unauthenticated401, PermissionDenied403, NotFound404.
- Removed this API's local Generic400/403/404 overrides from
  components/responses: they existed only to work around a P-040
  bundling name collision (introduced for issue camaraproject#72), which no longer
  applies now that the shared catalogue responses already carry
  exactly the same restricted code set this API needs.
- Locally-defined 409 responses (ALREADY_EXISTS/INCOMPATIBLE_STATE)
  now use the CAMARA_common.yaml Track-2 template (ErrorInfo allOf'd
  with a local status/code enum restriction) instead of a bare
  ErrorInfo $ref, matching the r4.4 Design Guide's required pattern
  for locally-defined error responses.

Local duplication of SinkCredential/AccessTokenCredential/sink/
SubscriptionConfig against the r4.4 CAMARA_event_common.yaml
equivalents (Sink, SinkCredential w/ PRIVATE_KEY_JWT, ConfigBase) is
tracked separately and not addressed in this commit.
…OT_SUPPORTED

Continues the Commonalities r4.4 migration for the implicit
subscription model used by createAppInstance/createAppDeployment:

- SubscriptionRequest.sink now $refs the shared Sink schema in
  CAMARA_event_common.yaml instead of duplicating its
  string/format/pattern/maxLength definition locally.
- SinkCredential no longer duplicates AccessTokenCredential's fields
  from scratch; it now allOf's the common AccessTokenCredential and
  locally restricts credentialType to ACCESSTOKEN only (PRIVATE_KEY_JWT,
  newly supported by Commonalities r4.4, is intentionally not offered
  by this API). The local AccessTokenCredential schema was removed as
  it's no longer needed.
- Added the new 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED response
  (components/responses/EventNotificationsNotSupported422, referencing
  the shared example in CAMARA_event_common.yaml) to both
  createAppInstance and createAppDeployment, and documented in their
  descriptions that providing subscriptionRequest.sink when the Edge
  Cloud Platform cannot deliver notifications results in this error
  without creating the resource.

Echoing `sink` back in AppInstanceInfo/AppDeploymentInfo on success,
as newly recommended by the Guide, is a separate schema change and is
not part of this commit.
Applies the two remaining recommended (SHOULD) items from the r4.4
Design Guide's Appendix B / request body strictness guidance:

- additionalProperties: false added to every request body schema (and
  inline request body) with no composition at its own top level:
  SubscriptionRequest, AppInstanceZoneRequest, AppInstanceClusterRequest,
  AppDeploymentZoneRequest, AppDeploymentClusterRequest, and the 4
  inline bodies of addEdgeCloudZone/removeEdgeCloudZone/
  addKubernetesCluster/removeKubernetesCluster. AppManifest is
  deliberately excluded: it's allOf'd into AppManifestInfo (adding the
  appId property), and additionalProperties: false on AppManifest
  itself would make that allOf combination invalid under standard
  JSON Schema semantics (the appId property, valid per the sibling
  allOf branch, would violate AppManifest's own restriction) - exactly
  the composition pitfall the Guide's "does not propagate through
  allOf" caveat warns about, just manifesting as a hard conflict
  rather than a silent no-op here.
- Reformatted enum descriptions that either had no per-value meaning,
  or had it as unstructured prose, into markdown bullet lists (one
  per Appendix B.3): SubscriptionEventType, AppInstanceInfo.status,
  AppManifest.packageType/appRepo.type/appRepo.authType,
  networkInterfaces.protocol/visibilityType, EdgeCloudZoneStatus,
  K8sAddons items, K8sNetworking.additionalNetworks.interfaceType,
  OperatingSystem.architecture/family/version/license, and the
  getEdgeCloudZones `status` query parameter.

Left the ALREADY_EXISTS/INCOMPATIBLE_STATE code enums on the
addEdgeCloudZone/addKubernetesCluster 409 responses as-is: their
per-value meaning is already documented via the existing
`examples[].description` entries, so a bullet list on the `code`
property itself would just duplicate that.
# Conflicts:
#	code/API_definitions/edge-application-management.yaml
@DLondonoD DLondonoD changed the title Comm r4.4 Sync Commonalities to r4.4 (0.9.0) Sep 23, 2026
Comment thread code/API_definitions/edge-application-management.yaml
Comment thread code/API_definitions/edge-application-management.yaml Outdated
Comment thread code/API_definitions/edge-application-management.yaml
Comment thread code/API_definitions/edge-application-management.yaml
Comment thread code/common/.sync-manifest.yaml
DLondonoD and others added 5 commits September 24, 2026 11:37
…llision

The local SinkCredential (allOf over common AccessTokenCredential,
restricted to ACCESSTOKEN) collides during bundling with the common
SinkCredential pulled in transitively via AccessTokenCredential's own
$ref, since both share the same name but different content. Renaming
the API-specific schema avoids the collision without touching the
shared Commonalities definitions.

Generated with aXet.code

Assisted-by: Claude Sonnet 5 via aXet.code <noreply@axetcode.local>
Co-authored-by: Sergi <sergialonsogarcia@gmail.com>
- Restore the implicit-subscription accessTokenExpiresUtc wording on
  AppEventSinkCredential, lost when it stopped duplicating
  AccessTokenCredential from scratch: the common schema only carries
  the explicit-subscription text (Event Guide §3.4, Note 3).
- Add locally-scoped CreateAppInstanceBadRequest400 /
  CreateAppDeploymentBadRequest400 responses (following the r4.4
  sample-implicit-events.yaml template) so createAppInstance and
  createAppDeployment's 400 also cover INVALID_SINK, INVALID_CREDENTIAL
  and INVALID_TOKEN, with an inline INVALID_CREDENTIAL example since
  this API only supports ACCESSTOKEN.
- Reference the shared AlreadyExists409 catalogue response instead of
  redefining an identical ALREADY_EXISTS-only 409 locally in submitApp,
  createAppInstance and createAppDeployment.
- Echo sink back on AppInstanceInfo/AppDeploymentInfo when event
  delivery is accepted, per the r4.4 Event Guide §2.1 "Sink delivery
  behaviour" MUST rule that comes with targeting Commonalities 0.9.0.

Generated with aXet.code

Assisted-by: Claude Sonnet 5 via aXet.code <noreply@axetcode.local>
# Conflicts:
#	code/API_definitions/edge-application-management.yaml

@Kevsy Kevsy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@JoseMConde
JoseMConde merged commit 990e207 into camaraproject:main Sep 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants