Skip to content

Conversation

@HenrikHL
Copy link
Contributor

@HenrikHL HenrikHL commented Feb 9, 2026

User description

SD-2812: Add the option to CANCEL a Shipping Instructions
Also fix a typo in descriptions


PR Type

Enhancement


Description

  • Extend cancel endpoint to support full Shipping Instructions cancellation

  • Add CANCELLED and DECLINED status values to Shipping Instructions

  • Update CancelShippingInstructionsUpdate schema with oneOf pattern

  • Clarify preconditions and postconditions for both cancel scenarios

  • Add example payloads for cancelling Shipping Instructions


Diagram Walkthrough

flowchart LR
  A["Cancel Endpoint"] -->|"UseCase 5"| B["Cancel Updated SI"]
  A -->|"UseCase 15"| C["Cancel Shipping Instructions"]
  B --> D["UPDATE_CANCELLED Status"]
  C --> E["CANCELLED Status"]
  F["New Statuses"] -->|"CANCELLED"| G["SI Schema"]
  F -->|"DECLINED"| G
Loading

File Walkthrough

Relevant files
Enhancement
EBL_v3.0.3.yaml
Extend cancel endpoint for full Shipping Instructions support

ebl/v3/EBL_v3.0.3.yaml

  • Extended PATCH /shipping-instructions/{documentReference} endpoint to
    support cancelling both Updated Shipping Instructions and full
    Shipping Instructions
  • Updated endpoint description to reference both UseCase 5 and UseCase
    15
  • Modified preconditions to specify different status requirements for
    each cancellation type
  • Refactored CancelShippingInstructionsUpdate schema using oneOf pattern
    to support both updatedShippingInstructionsStatus: UPDATE_CANCELLED
    and shippingInstructionsStatus: CANCELLED
  • Added CANCELLED and DECLINED status values to
    shippingInstructionsStatus enum in Shipping Instructions schema
  • Added example payloads demonstrating cancellation of full Shipping
    Instructions
  • Fixed typos in documentation (updatedShippingInstructionStatus
    updatedShippingInstructionsStatus)
+60/-18 
Configuration changes
styleguide.json
Styleguide configuration updates                                                 

.stoplight/styleguide.json

  • Minor configuration changes to styleguide
+1/-1     

@qodo-code-review
Copy link

qodo-code-review bot commented Feb 9, 2026

PR Compliance Guide 🔍

(Compliance updated until commit 742b54c)

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-2812
🟢 Add a new API endpoint/capability to cancel `Shipping Instructions` after submission.
Keep the solution consistent with the pattern used in Booking.
Codebase Duplication Compliance
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
🟢
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: Secure Error Handling

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

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: The new CancelShippingInstructionsUpdate oneOf schemas describe single allowed status
values but do not enforce them via enum, allowing arbitrary strings for
updatedShippingInstructionsStatus and shippingInstructionsStatus.

Referred Code
oneOf:
  - type: object
    title: Cancel Updated Shipping Instructions
    properties:
      updatedShippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |
          Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will be discontinue if the request is accepted by the provider.

          Only possible value to set is `UPDATE_CANCELLED`.
        example: UPDATE_CANCELLED
    required:
      - updatedShippingInstructionsStatus
  - type: object
    title: Cancel Shipping Instructions
    properties:
      shippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |


 ... (clipped 6 lines)

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Comprehensive Audit Trails

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status:
Spec-only change: This PR changes API specifications only (e.g., adds CANCELLED flow) and does not show any
runtime logging/audit implementation to verify that Shipping Instructions cancellations
are audit-logged with user ID, timestamp, action, and outcome.

Referred Code
tags:
  - Shipping Instructions
summary: |
  Cancels Shipping Instructions or Updated Shipping Instructions
operationId: patch-shipping-instructions
parameters:
  - $ref: '#/components/parameters/documentReference'
  - $ref: '#/components/parameters/Api-Version-Major'
description: |
  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`.

  This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.

  **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.

  ## Precondition
  In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
  - `UPDATE_RECEIVED`.

  Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
  - `RECEIVED`.


 ... (clipped 25 lines)

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:
Runtime handling unseen: The PR updates OpenAPI descriptions/examples for cancellation flows but does not include
service-side implementation changes, so validation of edge cases and failure handling
(e.g., invalid status transitions, missing resources) cannot be confirmed from the diff.

Referred Code
tags:
  - Shipping Instructions
summary: |
  Cancels Shipping Instructions or Updated Shipping Instructions
operationId: patch-shipping-instructions
parameters:
  - $ref: '#/components/parameters/documentReference'
  - $ref: '#/components/parameters/Api-Version-Major'
description: |
  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`.

  This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.

  **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.

  ## Precondition
  In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
  - `UPDATE_RECEIVED`.

  Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
  - `RECEIVED`.


 ... (clipped 136 lines)

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:
No logging shown: The PR modifies API specifications only and contains no application logging changes, so it
is not possible to verify structured logging and absence of sensitive data in logs for the
new cancel scenarios.

Referred Code
tags:
  - Shipping Instructions
summary: |
  Cancels Shipping Instructions or Updated Shipping Instructions
operationId: patch-shipping-instructions
parameters:
  - $ref: '#/components/parameters/documentReference'
  - $ref: '#/components/parameters/Api-Version-Major'
description: |
  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`.

  This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.

  **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.

  ## Precondition
  In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
  - `UPDATE_RECEIVED`.

  Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
  - `RECEIVED`.


 ... (clipped 25 lines)

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

Previous compliance checks

Compliance check up to commit 61b731e
Security Compliance
🟢
No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟢
🎫 #SD-2812
🟢 Add a new API endpoint/capability to cancel `Shipping Instructions` after submission.
Remain consistent with the pattern used in Booking.
Codebase Duplication Compliance
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
🟢
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: Secure Error Handling

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

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: The new CancelShippingInstructionsUpdate oneOf schemas describe “only possible value” for
updatedShippingInstructionsStatus and shippingInstructionsStatus but do not enforce it via
enum, weakening schema-level input validation for this external request payload.

Referred Code
oneOf:
  - type: object
    title: Cancel Updated Shipping Instructions
    properties:
      updatedShippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |
          Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will be discontinue if the request is accepted by the provider.

          Only possible value to set is `UPDATE_CANCELLED`.
        example: UPDATE_CANCELLED
    required:
      - updatedShippingInstructionsStatus
  - type: object
    title: Cancel Shipping Instructions
    properties:
      shippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |


 ... (clipped 6 lines)

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Comprehensive Audit Trails

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status:
Audit logging unclear: The PR extends the cancellation capability (UseCase 15) but the diff only updates the
OpenAPI spec and does not show whether the actual cancellation action is audit-logged with
user identity, timestamp, and outcome.

Referred Code
tags:
  - Shipping Instructions
summary: |
  Cancels Shipping Instructions or Updated Shipping Instructions
operationId: patch-shipping-instructions
parameters:
  - $ref: '#/components/parameters/documentReference'
  - $ref: '#/components/parameters/Api-Version-Major'
description: |
  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`.

  This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.

  **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.

  ## Precondition
  In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
  - `UPDATE_RECEIVED`.

  Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
  - `RECEIVED`.


 ... (clipped 11 lines)

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:
Runtime handling unknown: While the OpenAPI descriptions and examples were updated, the diff does not show backend
behavior for edge cases (e.g., cancelling when already processed), so robustness and
logging around these paths cannot be verified from the spec alone.

Referred Code
## Precondition
In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
- `UPDATE_RECEIVED`.

Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
- `RECEIVED`.
- `PENDING_UPDATE`

In order to cancel a `Shipping Instructions`, the status of the `Shipping Instructions` must be one of
- `RECEIVED`.
- `PENDING_UPDATE`

## Postcondition
The provider has received a cancellation from the consumer for an `Updated Shipping Instructions` or a `Shipping Instructions`.

The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not.

## Flow for the `202` (Accepted) response
The following occurs when a provider receives a cancellation:
1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.



 ... (clipped 123 lines)

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:
Logging not shown: The PR changes cancellation semantics but does not include application logging changes, so
it cannot be verified whether any logs added/used are structured and avoid sensitive data.

Referred Code
tags:
  - Shipping Instructions
summary: |
  Cancels Shipping Instructions or Updated Shipping Instructions
operationId: patch-shipping-instructions
parameters:
  - $ref: '#/components/parameters/documentReference'
  - $ref: '#/components/parameters/Api-Version-Major'
description: |
  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`.

  This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.

  **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.

  ## Precondition
  In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
  - `UPDATE_RECEIVED`.

  Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
  - `RECEIVED`.


 ... (clipped 11 lines)

Learn more about managing compliance generic rules or creating your own custom rules

Compliance check up to commit 4f3beba
Security Compliance
🟢
No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡
🎫 #SD-2812
🟢 Add/update API so there is an endpoint that allows cancelling Shipping Instructions after
submission.
Keep the solution consistent with the pattern used in Booking.
Codebase Duplication Compliance
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
🟢
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 Error Handling

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

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: The new CancelShippingInstructionsUpdate oneOf schemas define
updatedShippingInstructionsStatus and shippingInstructionsStatus as free-form strings
without enum constraints despite stating only UPDATE_CANCELLED/CANCELLED are allowed,
weakening schema-level input validation.

Referred Code
oneOf:
  - type: object
    title: Cancel Updated Shipping Instructions
    properties:
      updatedShippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |
          Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will discontinue if the request is accepted by the provider.

          Only possible value to set is `UPDATE_CANCELLED`.
        example: UPDATE_CANCELLED
    required:
      - updatedShippingInstructionsStatus
  - type: object
    title: Cancel Shipping Instructions
    properties:
      shippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |


 ... (clipped 6 lines)

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Comprehensive Audit Trails

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status:
Audit logging unclear: The PR adds/extends cancellation behavior for Shipping Instructions, but the diff only
updates the API specification and provides no evidence that the underlying cancellation
action is audit-logged with user identity, timestamp, action details, and outcome.

Referred Code
  Cancels Shipping Instructions or Updated Shipping Instructions
operationId: patch-shipping-instructions
parameters:
  - $ref: '#/components/parameters/documentReference'
  - $ref: '#/components/parameters/Api-Version-Major'
description: |
  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `shippingInstructionsReference` or a `transportDocumentReference` provided in `{documentReference}`.

  This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.

  **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to Cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.

  ## Precondition
  In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
  - `UPDATE_RECEIVED`.

  Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
  - `RECEIVED`.
  - `PENDING_UPDATE`

  In order to cancel a `Shipping Instructions`, the status of the `Shipping Instructions` must be one of


 ... (clipped 22 lines)

Learn more about managing compliance generic rules or creating your own custom rules

Compliance check up to commit 8de0151
Security Compliance
🟢
No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡
🎫 #SD-2812
🟢 Update the API to add support for cancelling Shipping Instructions after submission.
Keep the approach consistent with the pattern used in Booking.
Codebase Duplication Compliance
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
🔴
Generic: Meaningful Naming and Self-Documenting Code

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status:
Typos in identifiers: The endpoint description introduces misspelled identifiers (shippingInstrudctionsRefernce)
that reduce clarity and can mislead API consumers.

Referred Code
A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstrudctionsRefernce` or a `transportDocumentReference`.

This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.

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:
Weak schema validation: The cancel request schema allows any string for updatedShippingInstructionsStatus and
shippingInstructionsStatus (no enum), so invalid status values may still schema-validate
and lead to unclear failure modes.

Referred Code
oneOf:
  - type: object
    title: Cancel Updated Shipping Instructions
    properties:
      updatedShippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |
          Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will discontinue if the request is accepted by the provider.

          Only possible value to set is `UPDATE_CANCELLED`.
        example: UPDATE_CANCELLED
    required:
      - updatedShippingInstructionsStatus
  - type: object
    title: Cancel Shipping Instructions
    properties:
      shippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |


 ... (clipped 6 lines)

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 constraints: Although the descriptions say the only allowed values are UPDATE_CANCELLED/CANCELLED, the
schema defines these fields as unconstrained strings, weakening input validation for
external requests.

Referred Code
oneOf:
  - type: object
    title: Cancel Updated Shipping Instructions
    properties:
      updatedShippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |
          Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will discontinue if the request is accepted by the provider.

          Only possible value to set is `UPDATE_CANCELLED`.
        example: UPDATE_CANCELLED
    required:
      - updatedShippingInstructionsStatus
  - type: object
    title: Cancel Shipping Instructions
    properties:
      shippingInstructionsStatus:
        type: string
        maxLength: 50
        description: |


 ... (clipped 6 lines)

Learn more about managing compliance generic rules or creating your own custom rules

@HenrikHL HenrikHL requested a review from Copilot February 9, 2026 09:42
@qodo-code-review
Copy link

qodo-code-review bot commented Feb 9, 2026

PR Code Suggestions ✨

Latest suggestions up to 61b731e

CategorySuggestion                                                                                                                                    Impact
Incremental [*]
Make cancellation schema unambiguous

Improve the CancelShippingInstructionsUpdate schema by adding
additionalProperties: false and using enum for status fields to make it stricter
and prevent ambiguous payloads.

ebl/v3/EBL_v3.0.3.yaml [2700-2733]

 CancelShippingInstructionsUpdate:
-  type: object
   title: Cancel Shipping Instructions or Updated Shipping Instructions
   description: |
     Cancel the `Shipping Instructions` or the update to the `Shipping Instructions`
 
     **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.
   oneOf:
     - type: object
       title: Cancel Updated Shipping Instructions
+      additionalProperties: false
       properties:
         updatedShippingInstructionsStatus:
           type: string
           maxLength: 50
+          enum:
+            - UPDATE_CANCELLED
           description: |
-            Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will be discontinue if the request is accepted by the provider.
-
-            Only possible value to set is `UPDATE_CANCELLED`.
-          example: UPDATE_CANCELLED
+            Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will be discontinued if the request is accepted by the provider.
       required:
         - updatedShippingInstructionsStatus
     - type: object
       title: Cancel Shipping Instructions
+      additionalProperties: false
       properties:
         shippingInstructionsStatus:
           type: string
           maxLength: 50
+          enum:
+            - CANCELLED
           description: |
             Setting the `shippingInstructionsStatus` to `CANCELLED` cancels the `Shipping Instructions`. If accepted by the provider, the `Shipping Instructions` will be discontinued.
-
-            Only possible value to set is `CANCELLED`.
-          example: CANCELLED
       required:
         - shippingInstructionsStatus
  • Apply / Chat
Suggestion importance[1-10]: 8

__

Why: The suggestion correctly identifies that the oneOf schema can be made more robust by adding additionalProperties: false and using enum to enforce single valid values, which improves schema validation and prevents ambiguous payloads.

Medium
Possible issue
Forbid extra fields in variants

Add additionalProperties: false to both objects within the oneOf block for
CancelShippingInstructionsUpdate to prevent requests with extra fields, which
could cause validation to fail unexpectedly.

ebl/v3/EBL_v3.0.3.yaml [2707-2733]

 oneOf:
   - type: object
     title: Cancel Updated Shipping Instructions
+    additionalProperties: false
     properties:
       updatedShippingInstructionsStatus:
         type: string
         maxLength: 50
         description: |
           Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will be discontinue if the request is accepted by the provider.
 
           Only possible value to set is `UPDATE_CANCELLED`.
         example: UPDATE_CANCELLED
     required:
       - updatedShippingInstructionsStatus
   - type: object
     title: Cancel Shipping Instructions
+    additionalProperties: false
     properties:
       shippingInstructionsStatus:
         type: string
         maxLength: 50
         description: |
           Setting the `shippingInstructionsStatus` to `CANCELLED` cancels the `Shipping Instructions`. If accepted by the provider, the `Shipping Instructions` will be discontinued.
 
           Only possible value to set is `CANCELLED`.
         example: CANCELLED
     required:
       - shippingInstructionsStatus
  • Apply / Chat
Suggestion importance[1-10]: 8

__

Why: This suggestion correctly points out a potential issue with oneOf validation where a payload with both status fields would be rejected. Adding additionalProperties: false makes the schema stricter and prevents ambiguous requests, which is a critical improvement for API robustness.

Medium
  • Update

Previous suggestions

✅ Suggestions up to commit 4f3beba
CategorySuggestion                                                                                                                                    Impact
Possible issue
Reset regex state before use
Suggestion Impact:The PR updated the embedded Spectral ruleset code in .stoplight/styleguide.json (the "content" field), which is where PSEUDO_ENUM_PATTERN is defined/used, consistent with applying the suggested lastIndex reset fix.

code diff:

@@ -63,7 +63,7 @@

Reset the lastIndex property of the global regex PSEUDO_ENUM_PATTERN to 0 before
each use in .exec() loops and .test() calls. This prevents state-related issues
like missed matches from previous executions.

.stoplight/styleguide.json [66]

 const PSEUDO_ENUM_PATTERN = /\n *- *`?([A-Z0-9_.]+)`? *(\(|:)?/g;
 
 
 
 function checkLists(propertyName, text, list, isEnum, results) {
     let match;
     const fullMatches = [];
     const matches = [];
+
+    // IMPORTANT: reset lastIndex because PSEUDO_ENUM_PATTERN is global (/g)
+    PSEUDO_ENUM_PATTERN.lastIndex = 0;
+
     // Use a loop to find all matches
     while ((match = PSEUDO_ENUM_PATTERN.exec(text)) !== null) {
         fullMatches.push(match[0]);
         matches.push(match[1]); // Add the first capturing group to the list
         if (false && 'transportDocumentStatus' === propertyName) {
             results.push( { message: propertyName + `.description FULL MATCHES ` + match[0], }, );
             results.push( { message: propertyName + `.description exact MATCHES ` + match[1], }, );
         }
     }
     ...
 }
 
 function checkEnumAndPseudoEnum(input, propertyName, spec, results) {
     // - Only check for String types
     if ((spec && spec.type && spec.type === 'string' && !spec.format) || (!(spec && spec.type) && input && input.type && input.type === 'string')) {
         if (spec && spec.pseudoEnum) {
             ...
         } else {
             // Test the description for Enum or PseudoEnum values-descriptions
             if (input && input.description) {
                 if (input.enum) {
                     ...
                     checkLists(propertyName, input.description, input.enum, true, results);
                 } else {
                     // Make sure no PseudoEnum are present in the description
+                    PSEUDO_ENUM_PATTERN.lastIndex = 0;
                     if (PSEUDO_ENUM_PATTERN.test(input.description)) {
                         results.push( { message: propertyName + `.description contains a 'PseudoEnum'-pattern but the property is not defined as one.\nIf this is not a PseudoEnum then the spec must contain 'pseudoEnum: []'`, }, );
                     }
                 }
             }
         }
     }
 }
Suggestion importance[1-10]: 8

__

Why: The suggestion correctly identifies a potential bug where a stateful global regex (PSEUDO_ENUM_PATTERN) is reused, which can lead to incorrect validation results. Fixing this improves the correctness and reliability of the custom linter rule.

Medium
✅ Suggestions up to commit 5a9adbe
CategorySuggestion                                                                                                                                    Impact
Incremental [*]
Enforce allowed cancellation values

Add enum constraints to the updatedShippingInstructionsStatus and
shippingInstructionsStatus properties within the
CancelShippingInstructionsUpdate schema to enforce the single allowed values as
described in the documentation.

ebl/v3/EBL_v3.0.3.yaml [2700-2733]

 CancelShippingInstructionsUpdate:
   type: object
   title: Cancel Shipping Instructions and Update
   description: |
     Cancel the `Shipping Instructions` or the update to the `Shipping Instructions`
 
     **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to Cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.
   oneOf:
     - type: object
       title: Cancel Updated Shipping Instructions
+      additionalProperties: false
       properties:
         updatedShippingInstructionsStatus:
           type: string
           maxLength: 50
+          enum:
+            - UPDATE_CANCELLED
           description: |
             Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will discontinue if the request is accepted by the provider.
 
             Only possible value to set is `UPDATE_CANCELLED`.
           example: UPDATE_CANCELLED
       required:
         - updatedShippingInstructionsStatus
     - type: object
       title: Cancel Shipping Instructions
+      additionalProperties: false
       properties:
         shippingInstructionsStatus:
           type: string
           maxLength: 50
+          enum:
+            - CANCELLED
           description: |
             Setting the `shippingInstructionsStatus` to `CANCELLED` cancels the `Shipping Instructions`. The `Shipping Instructions` will discontinue if the request is accepted by the provider.
 
             Only possible value to set is `CANCELLED`.
           example: CANCELLED
       required:
         - shippingInstructionsStatus
Suggestion importance[1-10]: 8

__

Why: The suggestion correctly points out that the schema for CancelShippingInstructionsUpdate does not enforce the single allowed value for updatedShippingInstructionsStatus and shippingInstructionsStatus as stated in the description, which could lead to incorrect payloads being accepted.

Medium
Remove identifier ambiguity in docs
Suggestion Impact:Updated the endpoint description to state that the resource is identified by references provided in {documentReference}, though it still mentions both shippingInstructionsReference and transportDocumentReference rather than narrowing to only one type.

code diff:

       description: |
-        A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstructionsReference` or a `transportDocumentReference`.
+        A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `shippingInstructionsReference` or a `transportDocumentReference` provided in `{documentReference}`.

Clarify the description of the patch endpoint to remove ambiguity about which
type of reference is expected for the {documentReference} path parameter.

ebl/v3/EBL_v3.0.3.yaml [956-963]

 summary: |
   Cancels Shipping Instructions or Updated Shipping Instructions
 description: |
-  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstructionsReference` or a `transportDocumentReference`.
+  A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `shippingInstructionsReference` provided in `{documentReference}`.

[Suggestion processed]

Suggestion importance[1-10]: 6

__

Why: The suggestion correctly identifies an ambiguity in the API documentation where a single path parameter documentReference is described as accepting two different types of references, which can cause confusion for clients.

Low
Possible issue
Disallow unknown cancellation payload fields

Add additionalProperties: false to the oneOf schemas in
CancelShippingInstructionsUpdate to disallow unknown properties in the request
payload.

ebl/v3/EBL_v3.0.3.yaml [2700-2733]

 CancelShippingInstructionsUpdate:
   type: object
   title: Cancel Shipping Instructions and Update
   description: |
     Cancel the `Shipping Instructions` or the update to the `Shipping Instructions`
 
     **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to Cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.
   oneOf:
     - type: object
       title: Cancel Updated Shipping Instructions
+      additionalProperties: false
       properties:
         updatedShippingInstructionsStatus:
           type: string
           maxLength: 50
           description: |
             Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will discontinue if the request is accepted by the provider.
 
             Only possible value to set is `UPDATE_CANCELLED`.
           example: UPDATE_CANCELLED
       required:
         - updatedShippingInstructionsStatus
     - type: object
       title: Cancel Shipping Instructions
+      additionalProperties: false
       properties:
         shippingInstructionsStatus:
           type: string
           maxLength: 50
           description: |
             Setting the `shippingInstructionsStatus` to `CANCELLED` cancels the `Shipping Instructions`. The `Shipping Instructions` will discontinue if the request is accepted by the provider.
 
             Only possible value to set is `CANCELLED`.
           example: CANCELLED
       required:
         - shippingInstructionsStatus
Suggestion importance[1-10]: 6

__

Why: The suggestion correctly recommends adding additionalProperties: false to the oneOf schemas, which is a best practice for API definitions to ensure payloads are strictly validated and prevent potential interoperability issues.

Low
✅ Suggestions up to commit 8de0151
CategorySuggestion                                                                                                                                    Impact
High-level
Reconsider overloading PATCH for different cancellations
Suggestion Impact:The commit did not introduce new DELETE/POST cancel endpoints or remove the oneOf-overloaded PATCH design, but it updated the PATCH cancellation endpoint and related schema documentation to clarify the two cancellation cases and added version-compatibility guidance discouraging use of this endpoint to cancel an entire Shipping Instruction with older API versions.

code diff:

       tags:
         - Shipping Instructions
       summary: |
-        Cancels an update to or Cancels a Shipping Instructions
+        Cancels Shipping Instructions or Updated Shipping Instructions
       operationId: patch-shipping-instructions
       parameters:
         - $ref: '#/components/parameters/documentReference'
         - $ref: '#/components/parameters/Api-Version-Major'
       description: |
-        A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstrudctionsRefernce` or a `transportDocumentReference`.
+        A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`.
 
         This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.
+
+        **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.
 
         ## Precondition
         In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
         - `UPDATE_RECEIVED`.
 
+        Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
+        - `RECEIVED`.
+        - `PENDING_UPDATE`
+
         In order to cancel a `Shipping Instructions`, the status of the `Shipping Instructions` must be one of
         - `RECEIVED`.
-        - `PENDING_UPDATE`.
+        - `PENDING_UPDATE`
 
         ## Postcondition
         The provider has received a cancellation from the consumer for an `Updated Shipping Instructions` or a `Shipping Instructions`.
@@ -1100,7 +1106,7 @@
                     errors:
                       - errorCode: 7003
                         errorCodeText: Shipping Instructions does not contain an update
-                        errorCodeMessage: The Shipping Instructions has no update request - nothing to cancel
+                        errorCodeMessage: The Shipping Instructions have no update request - nothing to cancel
         '409':
           description: |
             In case the provider is already processing the `Updated Shipping Instructions` matching `shippingInstructionsReference='si-123'` it is possible to reject the `PATCH` request with a `409` (Conflict) response
@@ -1189,7 +1195,7 @@
                     statusCode: 429
                     statusCodeText: Too Many Requests
                     statusCodeMessage: |
-                      Too many request to patch a Shipping Instructions has been requested. Please try again in 1 hour
+                      Too many requests to patch a Shipping Instructions have been made. Please try again in 1 hour
                     providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                     errorDateTime: '2024-09-04T09:41:00Z'
                     errors:
@@ -1666,7 +1672,7 @@
                     statusCode: 429
                     statusCodeText: Too Many Requests
                     statusCodeMessage: |
-                      Too many request to fetch a Transport Document has been requested. Please try again in 1 hour
+                      Too many requests to fetch a Transport Document have been made. Please try again in 1 hour
                     providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                     errorDateTime: '2024-09-04T09:41:00Z'
                     errors:
@@ -1727,7 +1733,7 @@
       responses:
         '202':
           description: |
-            The approval of the `Transport Document` has been accepted and now awaits further processing
+            The approval of the `Transport Document` have been accepted and now awaits further processing
           headers:
             API-Version:
               $ref: '#/components/headers/API-Version'
@@ -1890,7 +1896,7 @@
                     statusCode: 429
                     statusCodeText: Too Many Requests
                     statusCodeMessage: |
-                      Too many request to patch a Transport Document has been requested. Please try again in 1 hour
+                      Too many requests to patch a Transport Document have been made. Please try again in 1 hour
                     providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                     errorDateTime: '2024-09-04T09:41:00Z'
                     errors:
@@ -2215,7 +2221,7 @@
                     statusCode: 429
                     statusCodeText: Too Many Requests
                     statusCodeMessage: |
-                      Too many request to create a Notification has been requested. Please try again in 1 hour
+                      Too many requests to create a Notification have been made. Please try again in 1 hour
                     providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                     errorDateTime: '2024-09-04T09:41:00Z'
                     errors:
@@ -2616,7 +2622,7 @@
                     statusCode: 429
                     statusCodeText: Too Many Requests
                     statusCodeMessage: |
-                      Too many request to create a Notification has been requested. Please try again in 1 hour
+                      Too many requests to create a Notification have been made. Please try again in 1 hour
                     providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                     errorDateTime: '2024-09-04T09:41:00Z'
                     errors:
@@ -2693,9 +2699,11 @@
     #####################################
     CancelShippingInstructionsUpdate:
       type: object
-      title: Cancel Shipping Instructions and Update
+      title: Cancel Shipping Instructions or Updated Shipping Instructions
       description: |
         Cancel the `Shipping Instructions` or the update to the `Shipping Instructions`
+
+        **👉Important note:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this endPoint to cancel a `Shipping Instructions`. Recipients implementing earlier versions **MAY ignore** such a request.
       oneOf:
         - type: object
           title: Cancel Updated Shipping Instructions
@@ -2704,7 +2712,7 @@
               type: string
               maxLength: 50
               description: |
-                Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will discontinue if the request is accepted by the provider.
+                Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will be discontinue if the request is accepted by the provider.
 
                 Only possible value to set is `UPDATE_CANCELLED`.
               example: UPDATE_CANCELLED
@@ -2717,7 +2725,7 @@
               type: string
               maxLength: 50
               description: |
-                Setting the `shippingInstructionsStatus` to `CANCELLED` cancels the `Shipping Instructions`. The `Shipping Instructions` will discontinue if the request is accepted by the provider.
+                Setting the `shippingInstructionsStatus` to `CANCELLED` cancels the `Shipping Instructions`. If accepted by the provider, the `Shipping Instructions` will be discontinued.
 
                 Only possible value to set is `CANCELLED`.
               example: CANCELLED
@@ -2837,21 +2845,21 @@
           maxLength: 50
           description: |
             The status of the `Shipping Instructions`. Possible values are:
-
-            - `RECEIVED` (Shipping Instructions has been received)
+            - `RECEIVED` (Shipping Instructions have been received)
             - `PENDING_UPDATE` (An update is required to the Shipping Instructions)
             - `COMPLETED` (The Shipping Instructions can no longer be modified - the related Transport Document has been surrendered for delivery)
-            - `CANCELLED` (The Shipping Instructions has been cancelled by Shipper)
-            - `DECLINED` (The Shipping Instructions has been declined by Carrier)
+            - `CANCELLED` (The Shipping Instructions have been cancelled by Shipper)
+            - `DECLINED` (The Shipping Instructions have been declined by Carrier)
+
+            **Condition:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use `CANCELLED` or `DECLINED` values. Recipients implementing earlier versions **MAY ignore** this property.

The current implementation overloads a single PATCH endpoint for two different
cancellation actions using a oneOf schema. It is suggested to use a more
explicit RESTful pattern, like using the DELETE verb or a dedicated POST
.../cancel endpoint for cancelling the entire Shipping Instruction, to improve
API clarity.

Examples:

ebl/v3/EBL_v3.0.3.yaml [957-978]
        Cancels an update to or Cancels a Shipping Instructions
      operationId: patch-shipping-instructions
      parameters:
        - $ref: '#/components/parameters/documentReference'
        - $ref: '#/components/parameters/Api-Version-Major'
      description: |
        A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstrudctionsRefernce` or a `transportDocumentReference`.

        This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**.


 ... (clipped 12 lines)
ebl/v3/EBL_v3.0.3.yaml [2694-2725]
    CancelShippingInstructionsUpdate:
      type: object
      title: Cancel Shipping Instructions and Update
      description: |
        Cancel the `Shipping Instructions` or the update to the `Shipping Instructions`
      oneOf:
        - type: object
          title: Cancel Updated Shipping Instructions
          properties:
            updatedShippingInstructionsStatus:

 ... (clipped 22 lines)

Solution Walkthrough:

Before:

# PATCH /shipping-instructions/{documentReference}
# Request body schema:
CancelShippingInstructionsUpdate:
  description: Cancel the SI or the update to the SI
  oneOf:
    - title: Cancel Updated Shipping Instructions
      properties:
        updatedShippingInstructionsStatus:
          example: UPDATE_CANCELLED
      required:
        - updatedShippingInstructionsStatus
    - title: Cancel Shipping Instructions
      properties:
        shippingInstructionsStatus:
          example: CANCELLED
      required:
        - shippingInstructionsStatus

After:

# Option 1: Use DELETE for cancelling the entire SI

# PATCH /shipping-instructions/{documentReference}
# Request body to cancel an SI *update*:
{ "updatedShippingInstructionsStatus": "UPDATE_CANCELLED" }

# DELETE /shipping-instructions/{documentReference}
# No request body needed to cancel the entire SI.

# Option 2: Use a dedicated action endpoint

# PATCH /shipping-instructions/{documentReference}
# (Same as Option 1 for cancelling an update)

# POST /shipping-instructions/{documentReference}/cancel
# No request body needed to cancel the entire SI.
Suggestion importance[1-10]: 8

__

Why: The suggestion correctly identifies a significant API design choice—overloading a PATCH endpoint for two distinct cancellation actions—and proposes valid RESTful alternatives, prompting a crucial discussion on API clarity and usability.

Medium
General
Enforce single allowed values with enum

Use the enum keyword to restrict the values for
updatedShippingInstructionsStatus and shippingInstructionsStatus to
UPDATE_CANCELLED and CANCELLED respectively.

ebl/v3/EBL_v3.0.3.yaml [2700-2725]

 +        - type: object
 +          title: Cancel Updated Shipping Instructions
 +          properties:
 +            updatedShippingInstructionsStatus:
 +              type: string
-+              maxLength: 50
 +              description: |
 +                Setting the `updatedShippingInstructionsStatus` to `UPDATE_CANCELLED` cancels the `Updated Shipping Instructions`. The `Updated Shipping Instructions` will discontinue if the request is accepted by the provider.
 +
 +                Only possible value to set is `UPDATE_CANCELLED`.
 +              example: UPDATE_CANCELLED
++              enum:
++                - UPDATE_CANCELLED
 +          required:
 +            - updatedShippingInstructionsStatus
 +        - type: object
 +          title: Cancel Shipping Instructions
 +          properties:
 +            shippingInstructionsStatus:
 +              type: string
-+              maxLength: 50
 +              description: |
 +                Setting the `shippingInstructionsStatus` to `CANCELLED` cancels the `Shipping Instructions`. The `Shipping Instructions` will discontinue if the request is accepted by the provider.
 +
 +                Only possible value to set is `CANCELLED`.
 +              example: CANCELLED
++              enum:
++                - CANCELLED
 +          required:
 +            - shippingInstructionsStatus
Suggestion importance[1-10]: 7

__

Why: The suggestion correctly identifies that using enum would create a stricter and more accurate API contract, which improves schema validation and clarity for consumers.

Medium
Restore missing precondition for cancellation
Suggestion Impact:The commit added an explicit additional precondition for UseCase 5 clarifying that, when cancelling an Updated Shipping Instructions, the associated underlying Shipping Instructions must be in RECEIVED or PENDING_UPDATE status (and also aligned list formatting).

code diff:

         ## Precondition
         In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
         - `UPDATE_RECEIVED`.
 
+        Additionally, for **UseCase 5 - Cancel update to Shipping Instructions**, the status of the underlying `Shipping Instructions` associated with the `Updated Shipping Instructions` must be one of
+        - `RECEIVED`.
+        - `PENDING_UPDATE`
+
         In order to cancel a `Shipping Instructions`, the status of the `Shipping Instructions` must be one of
         - `RECEIVED`.
-        - `PENDING_UPDATE`.
+        - `PENDING_UPDATE`

Restore the missing precondition that the Shipping Instructions status must be
RECEIVED or PENDING_UPDATE when cancelling an Updated Shipping Instructions.

ebl/v3/EBL_v3.0.3.yaml [967-973]

 +        ## Precondition
-+        In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be
-+        - `UPDATE_RECEIVED`.
++        In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be `UPDATE_RECEIVED` and the status of the `Shipping Instructions` must be one of:
++        - `RECEIVED`
++        - `PENDING_UPDATE`
 +
-+        In order to cancel a `Shipping Instructions`, the status of the `Shipping Instructions` must be one of
-+        - `RECEIVED`.
-+        - `PENDING_UPDATE`.
++        In order to cancel a `Shipping Instructions`, the status of the `Shipping Instructions` must be one of:
++        - `RECEIVED`
++        - `PENDING_UPDATE`
Suggestion importance[1-10]: 5

__

Why: The suggestion correctly points out an omission in the endpoint's precondition documentation, which is important for API consumers to understand the required state for the operation.

Low
Fix typo in reference name
Suggestion Impact:The commit updated the misspelled `shippingInstrudctionsRefernce` to `shippingInstructionsRefernce`, partially addressing the typo, but it did not fully correct it to `shippingInstructionsReference`.

code diff:

-        A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstrudctionsRefernce` or a `transportDocumentReference`.
+        A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstructionsRefernce` or a `transportDocumentReference`.

Correct the typo shippingInstrudctionsRefernce to shippingInstructionsReference
in the endpoint description.

ebl/v3/EBL_v3.0.3.yaml [963]

-The path can contain a `shippingInstrudctionsRefernce` or a `transportDocumentReference`.
+The path can contain a `shippingInstructionsReference` or a `transportDocumentReference`.
Suggestion importance[1-10]: 3

__

Why: The suggestion correctly identifies and fixes a typo in the documentation, which improves readability and prevents potential confusion for developers.

Low

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Extends the Shipping Instructions cancel endpoint to support cancelling both an SI update and the full Shipping Instructions, while updating the schema and documentation (including typo fixes).

Changes:

  • Expanded PATCH /shipping-instructions/{documentReference} docs to cover UseCase 5 and UseCase 15, including new examples.
  • Refactored CancelShippingInstructionsUpdate using oneOf to support UPDATE_CANCELLED and CANCELLED.
  • Added CANCELLED / DECLINED status wording to Shipping Instructions status descriptions and adjusted docs/typos.

Reviewed changes

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

File Description
ebl/v3/EBL_v3.0.3.yaml Extends cancel endpoint semantics, updates request schema via oneOf, adds examples, and updates SI statuses/docs.
.stoplight/styleguide.json Minor Stoplight styleguide configuration tweak.

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

@HenrikHL HenrikHL requested a review from Copilot February 9, 2026 10:09
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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


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

@HenrikHL HenrikHL requested a review from Copilot February 9, 2026 10:22
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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


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

@HenrikHL HenrikHL requested a review from Copilot February 9, 2026 10:32
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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


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

@HenrikHL HenrikHL requested a review from Copilot February 9, 2026 10:58
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 6 comments.


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

@HenrikHL HenrikHL requested a review from Copilot February 9, 2026 11:11
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.


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

@HenrikHL HenrikHL merged commit 827017f into master Feb 9, 2026
1 check passed
@HenrikHL HenrikHL deleted the SD-2812_Add-Cancel-SI branch February 9, 2026 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants