From 68635b2f8928b7ccd517665c64788405feb8a6b3 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Fri, 8 Aug 2025 08:48:24 +0200 Subject: [PATCH 01/31] remove the "Hashing Passwords" subsection --- documentation/CAMARA-API-Design-Guide.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 58fd8c60..c0439c5a 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -938,10 +938,6 @@ In the API response, provide relevant error message. Usernames, passwords, session tokens, and API keys SHOULD NOT appear in the URL, as this can be captured in web server logs, making them easily exploitable. See section [6.5. POST or GET for transferring sensitive or complex data](#65-post-or-get-for-transferring-sensitive-or-complex-data). -5. **Hashing passwords**. - - Passwords SHOULD never be transmitted in API bodies; however, if it becomes absolutely necessary, they MUST be hashed to protect the system and minimize potential damage in the event of a compromise. Utilizing strong hashing algorithms is crucial for password security. Effective options include Argon2, PBKDF2, bcrypt, and scrypt, which are designed to securely hash passwords and withstand various attack vectors. - For further guidance, please refer to the [OWASP API Security Project](https://owasp.org/www-project-api-security/). This resource offers comprehensive insights and best practices for securing APIs against common vulnerabilities and threats. ### 6.2. Security Definition @@ -1282,3 +1278,4 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` + From ea8329d906897c7c2e7d9399f94a2312bee9bbde Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 3 Sep 2025 14:57:52 +0200 Subject: [PATCH 02/31] Update VERSION.yaml --- VERSION.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION.yaml b/VERSION.yaml index b0f22b7e..0e257c62 100644 --- a/VERSION.yaml +++ b/VERSION.yaml @@ -1 +1 @@ -version: wip +version: version: 0.6.1 From 28ec2a768cca7962096f2589b17df9896efd6108 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 3 Sep 2025 14:59:25 +0200 Subject: [PATCH 03/31] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d862070d..9e823946 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ NOTE: Guidelines for Release Management of API versions, e.g. the API-Readiness- ## Status and released versions -* Version 0.6.0 of guidelines and assets for Fall25 meta-release of CAMARA APIs is available with the [r3.3 tag](https://github.com/camaraproject/Commonalities/tree/r3.3) +* Version 0.6.1 of guidelines and assets for Fall25 meta-release of CAMARA APIs is available with the [r3.4 tag](https://github.com/camaraproject/Commonalities/tree/r3.3) * Previous releases and pre-releases are available in https://github.com/camaraproject/Commonalities/releases For changes see [CHANGELOG.md](https://github.com/camaraproject/Commonalities/blob/main/CHANGELOG.md). From 7d87440f7b7bfa4a5496df140b194c54076a9386 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 3 Sep 2025 15:00:47 +0200 Subject: [PATCH 04/31] Update CAMARA_common.yaml --- artifacts/CAMARA_common.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 557a3ddd..3c022e4e 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -5,7 +5,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + version: 0.7.1 x-camara-commonalities: 0.6 paths: {} @@ -795,3 +795,4 @@ components: status: 504 code: TIMEOUT message: Request timeout exceeded. + From 81ce48a04dcbf950fb15eeebb5a58a4a1c47924c Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 3 Sep 2025 15:01:42 +0200 Subject: [PATCH 05/31] Update notification-as-cloud-event.yaml --- artifacts/notification-as-cloud-event.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 2aeaee70..660835e1 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -43,7 +43,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + version: 0.3.1 externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/Commonalities From 3542a3023eb6438cec2ec8852bfdac8e6f490892 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 3 Sep 2025 15:02:43 +0200 Subject: [PATCH 06/31] Update event-subscription-template.yaml --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index ea1d9927..7178ee41 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -12,7 +12,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + version: 0.3.1 x-camara-commonalities: 0.6 externalDocs: From 2db5fa3beeedab054bd174a33ef1f9e330601dc2 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 3 Sep 2025 20:11:50 +0200 Subject: [PATCH 07/31] Update CHANGELOG.md --- CHANGELOG.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc6d4e0c..96bdf450 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Changelog Commonalities ## Table of Contents +- **[r3.4](#r34)** - **[r3.3](#r33)** - **[r3.2](#r32)** - **[r3.1](#r31)** @@ -15,6 +16,17 @@ - **[v0.2.0](#v020)** - **[v0.1.0 - Initial version](#v010---initial-version)** +# r3.4 +## Release Notes + +This release contains Commonalities version 0.6.1 a patch release from [r3.3](#r33). + +### Fixed +* ErrorInfo schema properties order in template files aligned to [CAMARA API Design Guide](/documentation/CAMARA-API-Design-Guide.md) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/517 +* Fixed typo in [Gherkin Device Errors Template](/artifacts/testing/C01-device-errors.feature) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/523 + +**Full Changelog**: https://github.com/camaraproject/Commonalities/compare/r3.3...r3.4 + # r3.3 ## Release Notes From b4772a73b79b1d1a1dd8e7e4698dede7b12f93df Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 5 Sep 2025 16:38:06 +0200 Subject: [PATCH 08/31] Update CHANGELOG.md Co-authored-by: Kevin Smith --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96bdf450..65ae0b41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,7 @@ # r3.4 ## Release Notes -This release contains Commonalities version 0.6.1 a patch release from [r3.3](#r33). +This release contains Commonalities version 0.6.1, a patch release from [r3.3](#r33). ### Fixed * ErrorInfo schema properties order in template files aligned to [CAMARA API Design Guide](/documentation/CAMARA-API-Design-Guide.md) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/517 From 6afba2d04d8ec160778e64de4d456bd653b945c8 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Tue, 9 Sep 2025 10:51:32 +0200 Subject: [PATCH 09/31] Update README.md Co-authored-by: Kevin Smith --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9e823946..48383d37 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ NOTE: Guidelines for Release Management of API versions, e.g. the API-Readiness- ## Status and released versions -* Version 0.6.1 of guidelines and assets for Fall25 meta-release of CAMARA APIs is available with the [r3.4 tag](https://github.com/camaraproject/Commonalities/tree/r3.3) +* Version 0.6.1 of guidelines and assets for Fall25 meta-release of CAMARA APIs is available with the [r3.4 tag](https://github.com/camaraproject/Commonalities/releases/tag/r3.4) * Previous releases and pre-releases are available in https://github.com/camaraproject/Commonalities/releases For changes see [CHANGELOG.md](https://github.com/camaraproject/Commonalities/blob/main/CHANGELOG.md). From 223d7e9ace5fd28f3f505f57b4b56ce36572a2d7 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Tue, 9 Sep 2025 10:53:37 +0200 Subject: [PATCH 10/31] Update CHANGELOG.md --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65ae0b41..973ae503 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,10 @@ ## Release Notes This release contains Commonalities version 0.6.1, a patch release from [r3.3](#r33). +* Commonalities approved deliverables in **[documentation](https://github.com/camaraproject/Commonalities/tree/r3.4/documentation)** folder. +* Commonalities approved artifacts in **[artifacts](https://github.com/camaraproject/Commonalities/tree/r3.4/artifacts)** folder. + +**The relevant details of authentication and consent collection are covered by [release 3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases) of Identity and Consent Management Working Group documents.** ### Fixed * ErrorInfo schema properties order in template files aligned to [CAMARA API Design Guide](/documentation/CAMARA-API-Design-Guide.md) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/517 From 5f10d400fd706b5368e0eded4651ab52cc0ceddf Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Tue, 9 Sep 2025 10:05:06 +0100 Subject: [PATCH 11/31] fix: change networkAccessIdentifier to use `example.com` --- artifacts/CAMARA_common.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 557a3ddd..5fcb423c 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -100,7 +100,7 @@ components: NetworkAccessIdentifier: description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string - example: "123456789@domain.com" + example: "123456789@example.com" DeviceIpv4Addr: type: object @@ -795,3 +795,4 @@ components: status: 504 code: TIMEOUT message: Request timeout exceeded. + From 2d3c4b2fd26b71022622e16524df448d69a7ee7c Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Mon, 29 Sep 2025 15:15:18 +0200 Subject: [PATCH 12/31] Update event-subscription-template.yaml --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index ea1d9927..63753441 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -552,7 +552,7 @@ components: SubscriptionId: type: string - description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](/documentation/API-design-guidelines.md#122-event-notification). + description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, it SHALL be referred to as `subscriptionId` as per the Commonalities Event Notification Model. example: qs15-h556-rt89-1298 CloudEvent: From aaf0cce3d2d72c04c3eb6b8689f7a18195ac4e1c Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Mon, 29 Sep 2025 16:40:10 +0200 Subject: [PATCH 13/31] Fix x-correlator format --- artifacts/CAMARA_common.yaml | 2 +- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- documentation/CAMARA-API-Design-Guide.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 557a3ddd..617894ac 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -6,7 +6,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: "wip" paths: {} components: diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index ea1d9927..f1c0d7cd 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -13,7 +13,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: "wip" externalDocs: description: Product documentation at CAMARA diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 19573065..d058a06f 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -626,7 +626,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html # CAMARA Commonalities minor version - x.y - x-camara-commonalities: 0.5 + x-camara-commonalities: "0.5" ``` #### 5.3.1. Title From 0eecb7039bcb70292fe9b13b2dd3f9c5d6bc6d04 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Tue, 30 Sep 2025 11:41:20 +0200 Subject: [PATCH 14/31] Update VERSION.yaml --- VERSION.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION.yaml b/VERSION.yaml index 0e257c62..a9c96902 100644 --- a/VERSION.yaml +++ b/VERSION.yaml @@ -1 +1 @@ -version: version: 0.6.1 +version: 0.6.1 From cb773752e7f4104a37b1b0f6fa19c5643a67f982 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 3 Oct 2025 13:00:58 +0200 Subject: [PATCH 15/31] Update CAMARA-API-Event-Subscription-and-Notification-Guide.md --- .../CAMARA-API-Event-Subscription-and-Notification-Guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md b/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md index 8921e4ef..dea47582 100644 --- a/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md +++ b/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md @@ -508,7 +508,7 @@ curl -X 'POST' \ ```json { "id": 123654, - "source": "https://notificationSendServer12.supertelco.com", + "source": "https://notificationSendServer12.example.com", "type": "org.camaraproject.device-roaming-subscriptions.v1.roaming-status", "specversion": "1.0", "datacontenttype": "application/json", @@ -545,7 +545,7 @@ curl -X 'POST' \ ```json { "id": 123658, - "source": "https://notificationSendServer12.supertelco.com", + "source": "https://notificationSendServer12.example.com", "type": "org.camaraproject.api.device-roaming-subscriptions.v1.subscription-ended", "specversion": "1.0", "datacontenttype": "application/json", From 2f8016adc51091445080248a6e3615e227701212 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 3 Oct 2025 13:02:13 +0200 Subject: [PATCH 16/31] Update notification-as-cloud-event.yaml --- artifacts/notification-as-cloud-event.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 2aeaee70..f79b6d22 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -153,7 +153,7 @@ components: - Application-specific identifier: * /cloudevents/spec/pull/123 * 1-555-123-4567 - example: "https://notificationSendServer12.supertelco.com" + example: "https://notificationSendServer12.example.com" CloudEvent: description: The notification callback @@ -333,7 +333,7 @@ components: QOS_STATUS_CHANGED_EXAMPLE: value: id: "123e4567-e89b-12d3-a456-426655440000" - source: "https://notificationSendServer12.supertelco.com" + source: "https://notificationSendServer12.example.com" type: "org.camaraproject.quality-on-demand.v0.qos-status-changed" specversion: "1.0" time: "2023-01-17T13:18:23.682Z" From 2a23cd090f7c9cbc1e24495593f0db85b6cf48be Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 3 Oct 2025 13:03:09 +0200 Subject: [PATCH 17/31] Update event-subscription-template.yaml --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index ea1d9927..10576d45 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -609,7 +609,7 @@ components: - Application-specific identifier: * /cloudevents/spec/pull/123 * 1-555-123-4567 - example: "https://notificationSendServer12.supertelco.com" + example: "https://notificationSendServer12.example.com" DateTime: type: string From 659bc66196e351584e5afd6bb849dfdbc27e639e Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 3 Oct 2025 16:39:41 +0200 Subject: [PATCH 18/31] Update CHANGELOG.md --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 973ae503..ad19516d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,11 @@ This release contains Commonalities version 0.6.1, a patch release from [r3.3](# ### Fixed * ErrorInfo schema properties order in template files aligned to [CAMARA API Design Guide](/documentation/CAMARA-API-Design-Guide.md) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/517 * Fixed typo in [Gherkin Device Errors Template](/artifacts/testing/C01-device-errors.feature) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/523 +* Fixed link and description of `SubscriptionId` in event-subscription-template.yaml by @rartych in https://github.com/camaraproject/Commonalities/pull/536 +* Changed networkAccessIdentifier and notification server example to use `example.com` by @Kevsy in https://github.com/camaraproject/Commonalities/pull/530 + +### Removed +* Removed "Hashing Passwords" subsection from CAMARA API Design Guide by @AxelNennker in https://github.com/camaraproject/Commonalities/pull/511 **Full Changelog**: https://github.com/camaraproject/Commonalities/compare/r3.3...r3.4 From 09b54387c11ac8991b969a0e686e601a85c8ea15 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 10 Oct 2025 14:25:09 +0200 Subject: [PATCH 19/31] Update VERSION.yaml --- VERSION.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION.yaml b/VERSION.yaml index a9c96902..b0f22b7e 100644 --- a/VERSION.yaml +++ b/VERSION.yaml @@ -1 +1 @@ -version: 0.6.1 +version: wip From d19f4a72639680768d28fde3bdd72ce61b4f290d Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 10 Oct 2025 14:25:55 +0200 Subject: [PATCH 20/31] Meaning Clarification for {{API_NAME}}.{{SPECIFIC_CODE}} --- documentation/CAMARA-API-Design-Guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index eee166c7..99b368a0 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -228,7 +228,7 @@ To ensure interoperability, it is crucial to implement error management that str An error representation MUST NOT differ from the representation of any resource. A main error message is defined with JSON structure with the following fields: - A field `status`, which can be identified in the response as a standard code from a list of Hypertext Transfer Protocol (HTTP) response status codes. -- A unique error `code`, which can be identified and traced for more details. It MUST be human-readable; therefore, it MUST NOT be a numeric code. In turn, to achieve a better location of the error, you can reference the value or the field causing it, and include it in the message. +- A unique error `code`, which can be identified and traced for more details. It MUST be human-readable; therefore, it MUST NOT be a numeric code. In turn, to achieve a better location of the error, you can reference the value or the field causing it, and include it in the message. The format for this field MUST be `SCREAMING_SNAKE_CASE` (e.g. "INVALID_ARGUMENT"). - A detailed description in `message` - in English language in API specification, it can be changed to other languages in implementation if needed. All these aforementioned fields are mandatory in Error Responses. @@ -316,6 +316,8 @@ In the following, we elaborate on the existing client errors. In particular, we > _NOTE 2: A {{SPECIFIC_CODE}}, unless it may have traversal scope (i.e. re-usable among different APIs), SHALL follow this scheme for a specific API: {{API_NAME}}.{{SPECIFIC_CODE}}_ +> _NOTE 3: Meaning of {{API_NAME}}.{{SPECIFIC_CODE}}. The double curly brackets '{{..}}' represent a placeholder to be replaced with the real values for the exception. `API_NAME` is the value of [`api-name`](#551-api-name) in `SCREAMING_SNAKE_CASE` format while `SPECIFIC_CODE` represents the value agreed within a WG for a given API error case scenario, in `SCREAMING_SNAKE_CASE` format as well (e.g. CARRIER_BILLING.PAYMENT_DENIED)._ + **Mandatory Errors** to be **documented in CAMARA API Spec YAML** are the following: - For event subscriptions APIs, the ones defined in Event Subscription section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification.md) From fed327156e735a26109af634d547fca80d82bc6d Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 10 Oct 2025 14:26:04 +0200 Subject: [PATCH 21/31] Update CAMARA_common.yaml --- artifacts/CAMARA_common.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 357da204..81e96d27 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -5,7 +5,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.7.1 + version: wip x-camara-commonalities: 0.6 paths: {} @@ -796,3 +796,4 @@ components: code: TIMEOUT message: Request timeout exceeded. + From a0a46342c51e1bfbb4f4abf084d61b4d9c4e62c3 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 10 Oct 2025 14:27:20 +0200 Subject: [PATCH 22/31] Update notification-as-cloud-event.yaml --- artifacts/notification-as-cloud-event.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 16a3d424..46d15977 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -43,7 +43,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.3.1 + version: wip externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/Commonalities From 0bb76d1737c1b7c46b1627631baf0d3c0a7f023a Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 10 Oct 2025 14:27:52 +0200 Subject: [PATCH 23/31] Update event-subscription-template.yaml --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index c244d0d5..dedf9a9f 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -12,7 +12,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.3.1 + version: wip x-camara-commonalities: 0.6 externalDocs: From c718b203eb04da16482314e73f5fa902432d6de7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Tue, 14 Oct 2025 18:08:01 +0200 Subject: [PATCH 24/31] Update documentation/CAMARA-API-Design-Guide.md Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- documentation/CAMARA-API-Design-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 99b368a0..86626947 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -316,7 +316,7 @@ In the following, we elaborate on the existing client errors. In particular, we > _NOTE 2: A {{SPECIFIC_CODE}}, unless it may have traversal scope (i.e. re-usable among different APIs), SHALL follow this scheme for a specific API: {{API_NAME}}.{{SPECIFIC_CODE}}_ -> _NOTE 3: Meaning of {{API_NAME}}.{{SPECIFIC_CODE}}. The double curly brackets '{{..}}' represent a placeholder to be replaced with the real values for the exception. `API_NAME` is the value of [`api-name`](#551-api-name) in `SCREAMING_SNAKE_CASE` format while `SPECIFIC_CODE` represents the value agreed within a WG for a given API error case scenario, in `SCREAMING_SNAKE_CASE` format as well (e.g. CARRIER_BILLING.PAYMENT_DENIED)._ +> _NOTE 3: Meaning of {{API_NAME}}.{{SPECIFIC_CODE}}. The double curly brackets '{{..}}' represent a placeholder to be replaced with the real values for the exception. `API_NAME` is the value of [`api-name`](#551-api-name) in `SCREAMING_SNAKE_CASE` format while `SPECIFIC_CODE` represents the value agreed for a given API error case scenario, in `SCREAMING_SNAKE_CASE` format as well (e.g. CARRIER_BILLING.PAYMENT_DENIED)._ **Mandatory Errors** to be **documented in CAMARA API Spec YAML** are the following: From b9f4c2eeacc9616908561cf3ce8edb816ed89485 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 15 Oct 2025 13:20:02 +0200 Subject: [PATCH 25/31] adapt_format_for_specific_code_and_message_placeholder_values --- artifacts/CAMARA_common.yaml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 81e96d27..26786a5f 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -5,7 +5,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + version: wip x-camara-commonalities: 0.6 paths: {} @@ -309,8 +309,8 @@ components: description: Specific Syntax Exception regarding a field that is relevant in the context of the API value: status: 400 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } + code: "{{SPECIFIC_CODE}}" + message: "{{SPECIFIC_CODE_MESSAGE}}" Generic401: description: Unauthorized headers: @@ -373,8 +373,8 @@ components: description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API value: status: 403 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } + code: "{{SPECIFIC_CODE}}" + message: "{{SPECIFIC_CODE_MESSAGE}}" Generic404: description: Not found headers: @@ -412,8 +412,8 @@ components: description: Specific situation to highlight the resource/concept not found value: status: 404 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } + code: "{{SPECIFIC_CODE}}" + message: "{{SPECIFIC_CODE_MESSAGE}}" Generic405: description: Method Not Allowed headers: @@ -508,8 +508,8 @@ components: description: Specific conflict situation that is relevant in the context of the API value: status: 409 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } + code: "{{SPECIFIC_CODE}}" + message: "{{SPECIFIC_CODE_MESSAGE}}" Generic410: description: Gone headers: @@ -636,8 +636,8 @@ components: description: Any semantic condition associated to business logic, specifically related to a field or data structure value: status: 422 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } + code: "{{SPECIFIC_CODE}}" + message: "{{SPECIFIC_CODE_MESSAGE}}" Generic429: description: Too Many Requests headers: From d4464e4220d77a2e6c3acde5a91bb92b40595b71 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Sun, 19 Oct 2025 12:16:38 +0200 Subject: [PATCH 26/31] New 409 error code called WRONG_STATE --- artifacts/CAMARA_common.yaml | 7 +++++++ documentation/CAMARA-API-Design-Guide.md | 1 + 2 files changed, 8 insertions(+) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 81e96d27..a7678540 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -484,6 +484,7 @@ components: - ABORTED - ALREADY_EXISTS - CONFLICT + - WRONG_STATE - "{{SPECIFIC_CODE}}" examples: GENERIC_409_ABORTED: @@ -504,6 +505,12 @@ components: status: 409 code: CONFLICT message: A specified resource duplicate entry found. + GENERIC_409_WRONG_STATE: + description: A resource referenced in the request is in a wrong state for the requested operation + value: + status: 409 + code: WRONG_STATE + message: A referenced resource is in a wrong state. GENERIC_409_{{SPECIFIC_CODE}}: description: Specific conflict situation that is relevant in the context of the API value: diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index eee166c7..151133ab 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -278,6 +278,7 @@ In the following, we elaborate on the existing client errors. In particular, we | 409 | `ABORTED` | Concurrency conflict. | Concurrency of processes of the same nature/scope | | 409 | `ALREADY_EXISTS` | The resource that a client tried to create already exists. | Trying to create an existing resource | | 409 | `CONFLICT` | A specified resource duplicate entry found. | Duplication of an existing resource | +| 409 | `WRONG_STATE` | Resource state conflict. | A resource referenced in the request is in a wrong state for the requested operation | | 409 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific conflict situation that is relevant in the context of the API | Service Exceptions From 481629d9010554542075435d93dd49ebb218212a Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Fri, 24 Oct 2025 16:28:50 +0200 Subject: [PATCH 27/31] Correct link to CAMARA-API-Event-Subscription-and-Notification-Guide.md --- documentation/CAMARA-API-Design-Guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index eee166c7..a1126fe9 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -318,8 +318,8 @@ In the following, we elaborate on the existing client errors. In particular, we **Mandatory Errors** to be **documented in CAMARA API Spec YAML** are the following: -- For event subscriptions APIs, the ones defined in Event Subscription section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification.md) -- For event notifications flow, the ones defined in Event Notification section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification.md) +- For event subscriptions APIs, the ones defined in Event Subscription section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md) +- For event notifications flow, the ones defined in Event Notification section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md) - For the rest of APIs: - Error status 401 - Error status 403 From 876c50a13a7bee5f104d0c3feb3d9df09b2a88fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Mon, 27 Oct 2025 12:19:52 +0100 Subject: [PATCH 28/31] Update section 5.3 description.info example --- documentation/CAMARA-API-Design-Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 1b6a0872..9314eb19 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -626,7 +626,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html # CAMARA Commonalities minor version - x.y - x-camara-commonalities: "0.5" + x-camara-commonalities: "0.6" ``` #### 5.3.1. Title @@ -1279,3 +1279,4 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` + From 8066745c17e6fbbf5fa5255344ac36024f447ba0 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Mon, 27 Oct 2025 19:48:54 +0100 Subject: [PATCH 29/31] adapting_message_for_specific_code --- artifacts/CAMARA_common.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 26786a5f..f30c8af3 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -310,7 +310,7 @@ components: value: status: 400 code: "{{SPECIFIC_CODE}}" - message: "{{SPECIFIC_CODE_MESSAGE}}" + message: Message for specific code Generic401: description: Unauthorized headers: @@ -374,7 +374,7 @@ components: value: status: 403 code: "{{SPECIFIC_CODE}}" - message: "{{SPECIFIC_CODE_MESSAGE}}" + message: Message for specific code Generic404: description: Not found headers: @@ -413,7 +413,7 @@ components: value: status: 404 code: "{{SPECIFIC_CODE}}" - message: "{{SPECIFIC_CODE_MESSAGE}}" + message: Message for specific code Generic405: description: Method Not Allowed headers: @@ -509,7 +509,7 @@ components: value: status: 409 code: "{{SPECIFIC_CODE}}" - message: "{{SPECIFIC_CODE_MESSAGE}}" + message: Message for specific code Generic410: description: Gone headers: @@ -637,7 +637,7 @@ components: value: status: 422 code: "{{SPECIFIC_CODE}}" - message: "{{SPECIFIC_CODE_MESSAGE}}" + message: Message for specific code Generic429: description: Too Many Requests headers: From d57ea6a2d280868ce5f69734fe9c115e8b791e3b Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Wed, 19 Nov 2025 18:57:42 +0100 Subject: [PATCH 30/31] Changed to INCOMPATIBLE_STATE --- artifacts/CAMARA_common.yaml | 10 +++++----- documentation/CAMARA-API-Design-Guide.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index a7678540..5d51e372 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -484,7 +484,7 @@ components: - ABORTED - ALREADY_EXISTS - CONFLICT - - WRONG_STATE + - INCOMPATIBLE_STATE - "{{SPECIFIC_CODE}}" examples: GENERIC_409_ABORTED: @@ -505,12 +505,12 @@ components: status: 409 code: CONFLICT message: A specified resource duplicate entry found. - GENERIC_409_WRONG_STATE: - description: A resource referenced in the request is in a wrong state for the requested operation + GENERIC_409_INCOMPATIBLE_STATE: + description: A resource referenced in the request is in an incompatible state for the requested operation value: status: 409 - code: WRONG_STATE - message: A referenced resource is in a wrong state. + code: INCOMPATIBLE_STATE + message: A referenced resource is in an incompatible state. GENERIC_409_{{SPECIFIC_CODE}}: description: Specific conflict situation that is relevant in the context of the API value: diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 151133ab..b963b638 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -278,7 +278,7 @@ In the following, we elaborate on the existing client errors. In particular, we | 409 | `ABORTED` | Concurrency conflict. | Concurrency of processes of the same nature/scope | | 409 | `ALREADY_EXISTS` | The resource that a client tried to create already exists. | Trying to create an existing resource | | 409 | `CONFLICT` | A specified resource duplicate entry found. | Duplication of an existing resource | -| 409 | `WRONG_STATE` | Resource state conflict. | A resource referenced in the request is in a wrong state for the requested operation | +| 409 | `INCOMPATIBLE_STATE` | Resource state conflict. | A resource referenced in the request is in an incompatible state for the requested operation | | 409 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific conflict situation that is relevant in the context of the API | Service Exceptions From 8063e009a8d1dc048c20977e1d6a67c1ba78f431 Mon Sep 17 00:00:00 2001 From: tlohmar Date: Mon, 24 Nov 2025 14:57:53 +0100 Subject: [PATCH 31/31] Update documentation/CAMARA-API-Design-Guide.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ok. Co-authored-by: Pedro Díez García --- documentation/CAMARA-API-Design-Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index b963b638..4489a3b0 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -278,7 +278,8 @@ In the following, we elaborate on the existing client errors. In particular, we | 409 | `ABORTED` | Concurrency conflict. | Concurrency of processes of the same nature/scope | | 409 | `ALREADY_EXISTS` | The resource that a client tried to create already exists. | Trying to create an existing resource | | 409 | `CONFLICT` | A specified resource duplicate entry found. | Duplication of an existing resource | -| 409 | `INCOMPATIBLE_STATE` | Resource state conflict. | A resource referenced in the request is in an incompatible state for the requested operation | +| 409 | `INCOMPATIBLE_STATE` | A referenced resource is in an incompatible state. | A resource referenced in the request is in an incompatible state for the requested operation | + | 409 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific conflict situation that is relevant in the context of the API | Service Exceptions