Analysis of Commonalities 0.6.0

(DRAFT)

Updates from r3.2 (rc-1) to r3.3 (public release) are highlighted in blue.

See the table below summarizing changes

Changelog

Added

CAMARA API Design Guide document by @rartych in #441
CAMARA API Event Subscription and Notification Guide document by @bigludo7 in #442
Links to CAMARA API Event Subscription and Notification Guide in artifacts by @rartych in #453
Updated Glossary with Terminology from Device Identifier API by @eric-murray in camaraproject#454
Text description for duration format fields by @PedroDiez in camaraproject#459
Event versioning section added to Guide document by @tanjadegroot in #475
Not Documented Error Responses info.description section by @PedroDiez in #457
Enhancements Subscription/Notification Architecture for Fall25 by @PedroDiez in #464
Gherkin Feature: x-correlator format checking step since Fall25 by @PedroDiez in #480
Added event-notification feature file template by @bigludo7 in #470
Added Pairwise Pseudonymous Identifier to glossary by @eric-murray in #485
Recommendation and examples to provide schema context in test definitions by @PedroDiez in #492

Continuous release numbering guidelines in CAMARA API Design Guide by @tanjadegroot in #505

Changed

Align 401 wording in Notification Cloud Events Artifact by @PedroDiez in #449
Updated types property of Subscription allowing more than one event type per subscription by @eric-murray in #432 and clarification on using multiple event types by @rartych in #477
Request response definitions and other clarifications in chapter 5 of API Design Guide by @rartych in camaraproject#450
X-Correlator Format changed by @PedroDiez in camaraproject#463
Updated Security chapter in CAMARA-API-Design-Guide.md by @rartych in camaraproject#467
Sorting Logic Enhancements in CAMARA-API-Design-Guide.md by @PedroDiez in camaraproject#471
Linting rules definition updated by @rartych in camaraproject#466
Updated .gherkin-lintrc by @rartych in #472
Editorial improvements of Guide documents and keyword capitalization by @rartych in #494 and #501
Linting rules updated by @rartych in #502

Changed Mandatory Description for date-time string format and updated template files by @PedroDiez in #497

Fixed

Missing bullet point for Mandatory Errors restored in CAMARA API Design Guide by @rartych in #488
Editorial improvements of Guide documents by @rartych in #494
Clarified that the DeviceResponse schema is not mandatory by @eric-murray in #490

ErrorInfo scheme unification in CAMARA_common.yaml and event-subscription-template.yaml by @rartych in #506

Removed

Removed AUTHENTICATION_REQUIRED error code by @eric-murray in #429
API Design Guidelines document was deprecated by @rartych in #441
Removed IDENTIFIER_MISMATCH error and introduced DeviceResponse object by @eric-murray in #455
Removed IDENTIFIER_MISMATCH from testing artifacts by @jlurien in #479

Analysis

This sections presents of main changes that need to be introduced in API definitions and analysis of impact of changes.

PR	Changes	Required changes in OAS	Breaking change for API Provider implementation	Breaking change for API Client implementation

PR	Changes	Required changes in OAS	Breaking change for API Provider implementation	Breaking change for API Client implementation
Remove AUTHENTICATION_REQUIRED error code in #429	This PR removes the 401 `AUTHENTICATION_REQUIRED` code from the Commonalities documentation.	Potentially YES	Potentially YES	NO
Update `types` property of `Subscription` schema in event-subscription-template.yaml #432 #477	API sub-projects are free to decide to allow more than one event type per subscription. Use `SubscriptionEventType` schema in SubscriptionRequest `types` attribute Clarified in PR #477	Potentially YES (subscription APIs - only if the API wants to use the new possibility)	Potentially YES (subscription APIs only)	NO
Remove IDENTIFIER_MISMATCH error #455	the API provider must not respond with an error if the identifiers do not match, but instead use only one of the supplied identifiers and indicate which one in the API response. APIs that accept the `Device` object in the request should include an optional `DeviceResponse` object in the response to all the used device identifier to be notified to the API consumer. Changes in test definitions as indicated in PR #479 Clarified in PR #490	YES	YES	NO
Not Documented Error Responses info.description #457	Mandatory text proposed	YES	NO	NO
Text description aligment for duration format fields #459	Mandatory text proposed when `duration` string format is used	Potentially YES	NO (change required only if proprietary string format was used for duration attribute)	NO (change required only if proprietary string format was used for duration attribute)
X-Correlator Format Change #463	Update x-correlator pattern Use schema defined in the row below	YES	NO	NO
Gherkin Feature: x-correlator format checking step #480	Added schema XCorrelator and respective test `schema: $ref: "#/components/schemas/XCorrelator" schemas: XCorrelator: type: string pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"`	YES	NO	NO
Enhancements Subscription/Notification Architecture #464	3.4 `subscription-ends` --> `subscription-ended` 3.2 `subscription-started` optional event 3.3 `subscription-updated` optional event Added `sink` pattern and specific `400 - INVALID_SINK` error	YES (subscription APIs only)	YES (subscription APIs only)	YES (subscription APIs only)
Add event-notification feature file template #470	The template for Subscription API test definition (Gherkin file) added	NO	NO	NO
Added event-notification feature file template #470	Test definition template to be used by CAMARA subprojects when an event subscription resource is provided	NO	NO	NO
Recommendation and examples to provide schema context in test definitions #492	Every feature may include a context after the `Feature` tag to provide relevant information about the implementation and execution of the tests. This feature context is RECOMMENDED unless it does not provide additional value (e.g. all the info could have been given in the Background section for a certain API)	NO	NO	NO
Changed Mandatory Description for date-time string format and updated template files #497	Mandatory text shortened: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)`. Additional sentence can be removed, but can stay as non-mandatory text in the description of string parameter with `date-time` format	OPTIONAL	NO	NO
Clarified that the DeviceResponse schema is not mandatory #490	The `DeviceResponse` schema is not mandatory for an API If used in a response definition, however, the API provider: MUST include in the response which device identifier is being used when multiple have been provided MAY always include the device identifier in the response even when only one has been provided Related to PR #455	implemeted in M3 with #455	implemeted in M3 with #455	NO
ErrorInfo scheme unification in CAMARA_common.yaml and event-subscription-template.yaml #506	Change ErrorInfo schema in API specification to the schema defined in CAMARA_common.yaml As indicated in Commonalities #515 change of order of properties in ErrorInfo schema is confusing. Subprojects should follow API Design Guide where the original order of properties is defined: status->code->message	OPTIONAL	NO	NO