EBL 3.0: SD-2442: Add FeedbackElement object in Surrender response

[HenrikHL]

User description

SD-2442: Add FeedbackElement in Surrender responses

---

PR Type

Enhancement

---

Description

• Add FeedbackElement object to Surrender response schema

• Enable detailed feedback on surrender request processing

• Support multiple severity levels (ERROR, WARN, INFO)

• Include JSONPath property references for specific issues

---

Diagram Walkthrough

flowchart LR
  SR["Surrender Response"] -->|contains| FE["FeedbackElement"]
  FE -->|has| SEV["Severity<br/>ERROR/WARN/INFO"]
  FE -->|has| MSG["Message<br/>Human readable"]
  FE -->|has| PATH["PropertyPath<br/>JSONPath reference"]

Loading

File Walkthrough

	Relevant files
Enhancement	EBL_SUR_v3.0.3.yaml Add FeedbackElement schema to Surrender response                  ebl/v3/surrender/EBL_SUR_v3.0.3.yaml Added feedbackElements array property to Surrender response schema Created new FeedbackElement object schema with severity, message, and propertyPath properties Enhanced comments field description formatting with multi-line block scalar Defined severity levels (ERROR, WARN, INFO) with detailed descriptions +39/-1
Configuration changes	styleguide.json Update styleguide configuration                                                    .stoplight/styleguide.json Modified styleguide configuration file +1/-1

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡	🎫 #SD-2442 🟢 Add an optional error object/array to the Surrender response to support multiple errors (backward compatible extension). 🔴 Reuse an existing, consistent data structure for errors/feedback (preferably the existing errors array) rather than introducing a new structure, unless agreed otherwise. ⚪ Review/confirm the proposed error/feedback structure and content with CMA CGM/ICE (stakeholder validation of semantics/content).
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Missing enum validation: FeedbackElement.severity describes allowed values (ERROR/WARN/INFO) but does not enforce them via an enum, weakening input validation. Referred Code severity: type: string maxLength: 50 description: | Code denoting the severity of a `FeedbackElement`. Possible values are: - `ERROR` - Error that fully or partially prevents the correct processing of the request - `WARN` - Warning about the request being processed in a potentially unexpected way - `INFO` - Informational message about how the request is processed example: ERROR Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: User-facing details: The schema allows arbitrary user-relayable FeedbackElement.message content, which could unintentionally expose sensitive internal details depending on how producers populate it. Referred Code message: type: string maxLength: 5000 description: | Human readable feedback message that can be programmatically relayed to a user. example: An unexpected internal error occured propertyPath: Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[Copilot]

Pull request overview

This PR enhances the Surrender response schema by adding a structured feedback mechanism to communicate processing issues and information back to API consumers.

Changes:

• Added FeedbackElement object with severity levels (ERROR, WARN, INFO) to enable detailed feedback on surrender request processing
• Enhanced the comments field description formatting for improved readability
• Introduced JSONPath property references to pinpoint specific issues in the request payload

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 3 comments.

File	Description
EBL_SUR_v3.0.3.yaml	Added feedbackElements array property to Surrender response schema and defined new FeedbackElement object with severity, message, and propertyPath fields
styleguide.json	Updated styleguide configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Reuse a common feedback/error object Instead of defining a new FeedbackElement schema locally, reuse a common, standardized feedback or error object if one exists to ensure API consistency and reduce maintenance. Examples: ebl/v3/surrender/EBL_SUR_v3.0.3.yaml [788-815] FeedbackElement: type: object title: Feedback Element description: | An individual piece of feedback (potentially out of several) providing information on how the Surrender request is processed. properties: severity: type: string maxLength: 50 description: | ... (clipped 18 lines) Solution Walkthrough: Before: # ebl/v3/surrender/EBL_SUR_v3.0.3.yaml components: schemas: SurrenderResponse: properties: ... feedbackElements: type: array items: $ref: '#/components/schemas/FeedbackElement' FeedbackElement: # Defined locally within this file type: object title: Feedback Element properties: severity: type: string message: type: string propertyPath: type: string After: # ebl/v3/surrender/EBL_SUR_v3.0.3.yaml components: schemas: SurrenderResponse: properties: ... feedbackElements: type: array items: # Reference a common, shared schema file $ref: '../../common/schemas/FeedbackElement.yaml' # Note: The 'FeedbackElement' definition would be moved to a shared file # like 'common/schemas/FeedbackElement.yaml' instead of being local. Suggestion importance[1-10]: 9 __ Why: This is a critical API design suggestion that correctly points out the risk of creating a local FeedbackElement schema, which can lead to API inconsistency and higher maintenance, a concern also raised in the associated ticket.	High
Possible issue	Make feedback properties required Add a required constraint for the severity and message properties within the FeedbackElement schema to ensure all feedback is meaningful. ebl/v3/surrender/EBL_SUR_v3.0.3.yaml [788-815] FeedbackElement: type: object title: Feedback Element description: | An individual piece of feedback (potentially out of several) providing information on how the Surrender request is processed. properties: severity: type: string maxLength: 50 description: | Code denoting the severity of a `FeedbackElement`. Possible values are: - `ERROR` - Error that fully or partially prevents the correct processing of the request - `WARN` - Warning about the request being processed in a potentially unexpected way - `INFO` - Informational message about how the request is processed example: ERROR message: type: string maxLength: 5000 description: | Human readable feedback message that can be programmatically relayed to a user. example: An unexpected internal error occured propertyPath: type: string maxLength: 1000 description: | [JSONPath](https://github.com/json-path/JsonPath) within the request message of the specific property about which the feedback is provided (if applicable). example: $.endorsementChain[2].actionCode + required: + - severity + - message Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that a FeedbackElement is not useful without its core properties and proposes making severity and message required, which significantly improves the API schema's robustness.	Medium
	Enforce at least one feedback element Add minItems: 1 to the feedbackElements array schema to align it with its description, which states that at least one element is expected. ebl/v3/surrender/EBL_SUR_v3.0.3.yaml [776-783] feedbackElements: type: array description: | Feedback elements indicating why the Surrender request could not be processed. At least one feedback element of severity `ERROR` is expected. Lower severity feedback elements may also be included. items: $ref: '#/components/schemas/FeedbackElement' + minItems: 1 Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out a discrepancy between the schema's description and its constraints, proposing minItems: 1 to enforce the documented requirement and improve schema consistency.	Low
General	Enforce severity values using an enum Enforce the allowed values for the severity property (ERROR, WARN, INFO) by using an enum in the schema, and remove the now-redundant maxLength constraint. ebl/v3/surrender/EBL_SUR_v3.0.3.yaml [794-803] severity: type: string - maxLength: 50 description: | Code denoting the severity of a `FeedbackElement`. Possible values are: - `ERROR` - Error that fully or partially prevents the correct processing of the request - `WARN` - Warning about the request being processed in a potentially unexpected way - `INFO` - Informational message about how the request is processed example: ERROR + enum: + - ERROR + - WARN + - INFO Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly proposes using an enum to enforce the allowed values for the severity field, which makes the schema stricter and more self-documenting than just relying on the description.	Medium
Update