sync2

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,26 @@
 - **[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).
+* 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
+* 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
+
 # r3.3
 ## Release Notes
 

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/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).

artifacts/CAMARA_common.yaml

@@ -5,8 +5,8 @@ info:
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: wip
-  x-camara-commonalities: 0.6
+  version:  wip
+  x-camara-commonalities: "0.6"
 
 paths: {}
 components:
@@ -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
@@ -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: Message for specific code
     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: Message for specific code
     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: Message for specific code
     Generic405:
       description: Method Not Allowed
       headers:
@@ -484,6 +484,7 @@ components:
                       - ABORTED
                       - ALREADY_EXISTS
                       - CONFLICT
+                      - INCOMPATIBLE_STATE
                       - "{{SPECIFIC_CODE}}"
           examples:
             GENERIC_409_ABORTED:
@@ -504,12 +505,18 @@ components:
                 status: 409
                 code: CONFLICT
                 message: A specified resource duplicate entry found.
+            GENERIC_409_INCOMPATIBLE_STATE:
+              description: A resource referenced in the request is in an incompatible state for the requested operation
+              value:
+                status: 409
+                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:
                 status: 409
-                code: { { SPECIFIC_CODE } }
-                message: { { SPECIFIC_CODE_MESSAGE } }
+                code: "{{SPECIFIC_CODE}}"
+                message: Message for specific code
     Generic410:
       description: Gone
       headers:
@@ -636,8 +643,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: Message for specific code
     Generic429:
       description: Too Many Requests
       headers:
@@ -795,3 +802,5 @@ components:
                 status: 504
                 code: TIMEOUT
                 message: Request timeout exceeded.
+
+

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: "0.6"
 
 externalDocs:
   description: Product documentation at CAMARA
@@ -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:
@@ -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

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"

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.
@@ -278,6 +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`     | 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                                                          |
 
 <font size="3"><span style="color: blue"> Service Exceptions </span></font>
@@ -316,10 +318,12 @@ 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 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)
-- 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
@@ -626,7 +630,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
@@ -938,10 +942,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
@@ -1283,3 +1283,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.
 ```
 
+

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",