Cloudevents decoupled from EventTypeNotification scheme in Event Subscription Template

[rartych]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

Refactors the notification event schema hierarchy in the subscription template to decouple the CloudEvents 1.0 envelope from CAMARA-specific type constraints and discriminator routing.

The original CloudEvent schema mixed up three separate issues — the message format, the event types, and the routing rules — which made it hard to reuse the basic schema for different APIs or to add new event groups without changing shared parts.

This PR introduces a layered schema model:

• CloudEvent (Commonalities-owned) — pure CloudEvents 1.0 envelope. type is astring. No CAMARA-specific enum values, no discriminator. This schema is now stable and requires no modification regardless of how many APIs or event types are added.
• ApiNotificationEvent (API project-owned) — extends CloudEvent via allOf. Constrains type to ApiEventType and owns the discriminator mapping for API-specific concrete event schemas. Adding a new event type requires only a new enum value in ApiEventType and a new discriminator mapping entry here.
• ApiEventType (API project-owned) — standalone enum of API-specific event type strings. Separated from the discriminated schema so the valid type strings can be referenced independently (e.g. in SubscriptionRequest.types).
• SubscriptionLifecycleEvent + SubscriptionLifecycleEventType (Commonalities-owned) — structurally parallel to the API-specific group. Covers subscription-started, subscription-updated, subscription-ended.
• NotificationEvent (API project-owned) — oneOf union used as the callback requestBody schema. Adding a new event group requires a single line in the oneOf.

As a secondary fix, SubscriptionRequest.types and Subscription.types now reference ApiEventType instead of the previous SubscriptionEventType / EventTypeNotification enums, which incorrectly included lifecycle event types. Lifecycle events are server-initiated and must not appear as subscribable types in a POST body.

Which issue(s) this PR fixes:

Fixes #600

Does this PR introduce a breaking change?

• Yes
• No

The callback requestBody schema changes from CloudEvent to NotificationEvent. For implementations that performed strict schema validation against CloudEvent at the callback endpoint, this is a schema reference change but not a wire-format change — valid payloads under the old schema remain valid under the new one. The SubscriptionRequest.types / Subscription.types change removes lifecycle event types from the subscribable enum; if any implementation accepted (and ignored) lifecycle types in POST body, those values would now be rejected as invalid.

Special notes for reviewers:

• The layering is designed for split-file use as propose in Restructure artifacts directory for $ref consumption and bundling #603 : CloudEvent, SubscriptionLifecycleEvent, and SubscriptionLifecycleEventType are candidates for CAMARA_event_common.yaml ; ApiNotificationEvent, ApiEventType, and NotificationEvent belong in the sample-service-subscriptions.yaml. Note: For SubscriptionLifecycleEvent, and SubscriptionLifecycleEventType the special events naming pattern should be reviewed to make them reusable in the future.
• OAS 3.0 discriminators require that the propertyName field appear in the schema that declares the discriminator, not only in a parent via allOf. The type property override in ApiNotificationEvent and SubscriptionLifecycleEvent satisfies this constraint.
• NotificationEvent intentionally carries no discriminator. Without a top-level discriminator, tooling resolves the oneOf by evaluating each branch in order. This is correct behaviour — the two groups are distinguished by non-overlapping type enum values, so evaluation is unambiguous.
• The EventApiSpecific1 / EventApiSpecific2 concrete schemas now extend ApiNotificationEvent rather than CloudEvent directly, preserving the full inheritance chain and can be placed in sample-event-type.yaml.

Changelog input

refactor: decouple CloudEvent envelope from event type constraints in Event Subscription Template

Additional documentation

[PedroDiez]

Great work @rartych! Descriptive information provided will help a lot in understanding this enhanced model

Just minor editorial suggestions

LGTM at functional level

[PedroDiez]

do we take advantage and also update it?

[hdamker]

It's already done in #599 and need to be aligned to resolve the merge conflict.

[rartych]

I have resolved it, but diffs the file as completely new.

[hdamker]

The diffs shown on all lines are whitespace diffs, more precisely changes from LF to CRLF. https://github.com/camaraproject/Commonalities/pull/604/changes?w=1 is looking good and shows only the actual changes.

The main culprit is 939d6f6 which introduced four changed lines with CRLF (no clue why). The Merge conflict resolution in c67a8ea then aligned all lines to CRLF (Lines changed: 1396 additions & 1396 deletions) :-(

We might can avoid this behavior by deploying the .gitattributes file as proposed in camaraproject/tooling#112 ... would be worth to give it a try.

[hdamker]

I tried what would happen with adding .gitattributes and then git . add --renormalize:

artifacts/CAMARA_common.yaml                       | 1654 +++++------
 .../event-subscription-template.feature            |  758 ++---
 .../event-subscription-template.yaml               | 2794 +++++++++----------
 artifacts/testing/C01-device-errors.feature        |  216 +-
 artifacts/testing/C02-phoneNumber-errors.feature   |  158 +-
 documentation/API-DocumentationTemplate.md         |   40 +-
 documentation/CAMARA-API-Design-Guide.md           | 2888 ++++++++++----------
 documentation/Linting-rules.md                     |  924 +++----
 .../Nokia_Open_APIs_Lab_NEF_access.md              |   52 +-
 .../SupportingDocuments/UE-Identification.md       |  262 +-

So several main documents have currently CRLF line endings instead of LF. We need to do the introduction of .gitattributes and renormalization in a quiet phase to avoid merge conflicts.

[hdamker]

When SubscriptionLifecycleEvent moves to CAMARA_event_common.yaml as proposed, should the discriminator mapping with api-name-specific prefixes stay in the API template, or should the common file carry a generic mapping?

[rartych]

Good point.
Currently org.camaraproject.api-name.v0.subscription-* event names are API specific (although the guidelines are not explicit about the naming pattern for this events).
I propose to keep the schemas SubscriptionLifecycleEvent and SubscriptionLifecycleEventType in the api definitions, and in the future analyse the consequences of having common naming like org.camaraproject.subscription-event.v0.subscription-* in all subscription APIs.

[hdamker]

Same as above ... if "these are managed by Commonalities and are identical across all CAMARA APIs that support explicit subscriptions" then they should not contain the api-name placeholder.

[rartych]

As in #604 (comment) - the comments in the file can be improved to indicate that schemas are managed by Commonalities, and only event names should be updated with correct api-name

[rartych]

As explained in #604 (comment) Github diff is not readable.
You can see the changes : here

[PedroDiez]

LGTM

[patrice-conil]

LGTM

[bigludo7]

Thanks Rafal

[hdamker]

As explained in #604 (comment) Github diff is not readable.
You can see the changes : here

nice view in "mergely" ... but also readable in GitHub if you hide the whitespace changes: https://github.com/camaraproject/Commonalities/pull/604/changes?w=1 (also available via the UI, at the settings buttons in file changes view).

PR looks good to me as well.