EBL 3.0: SD-2502: Add shippingInstructionsRevisionNumber to SI

[HenrikHL]

User description

SD-2502: Add shippingInstructionsRevisionNumber to SI

---

PR Type

Enhancement

---

Description

• Add shippingInstructionsRevisionNumber field to track SI versions

• Field added to three Shipping Instructions schema components

• Integer type with auto-incrementing version tracking capability

• Ensures carrier uses most recent SI update for Transport Document

---

Diagram Walkthrough

flowchart LR
  SI["Shipping Instructions"] -->|add revision tracking| SIRev["shippingInstructionsRevisionNumber"]
  SIRev -->|integer type| Version["Version Number"]
  Version -->|increments on update| TD["Transport Document Creation"]

Loading

File Walkthrough

	Relevant files
Enhancement	EBL_v3.0.3.yaml Add revision number field to SI schemas                                    ebl/v3/EBL_v3.0.3.yaml Added shippingInstructionsRevisionNumber integer field to CreateShippingInstructionsRequest schema Added shippingInstructionsRevisionNumber integer field to ShippingInstructions schema Added shippingInstructionsRevisionNumber integer field to ShippingInstructionsResponse schema Field includes description explaining version tracking and example value of 1 +15/-0
Configuration changes	styleguide.json Styleguide configuration updates                                                  .stoplight/styleguide.json Minor configuration or styling updates +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-2502 🟢 The attribute name should be 'shippingInstructionsRevisionNumber'. The attribute type must be integer, starting at 1. Provide a description explaining it increments by one with each SI update and higher values are newer. Apply the attribute to relevant Shipping Instructions schema components used in EBL 3.0.3 (SI) API. ⚪ Add an optional 'Shipping Instructions Revision Number' attribute before the 'transportDocumentReference' field in Shipping Instructions.
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: 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: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No audit logs: The added schema fields introduce version-tracking semantics but no logging or audit trail is evident in the diff to capture changes or access to these critical SI revisions. Referred Code shippingInstructionsRevisionNumber: type: integer description: | The version number of the **Shipping Instructions** provided by the customer to ensure the carrier uses the most recent update when creating the **Transport Document**. This value is expected to increment by one with each **Shipping Instructions** update, with higher values representing newer versions. example: 1 transportDocumentReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 20 description: | A unique number allocated by the shipping line, for the shipper to indicate which `transportDocumentReference` should be linked with this `Shipping Instructions`. example: HHL71800000 transportDocumentTypeCode: type: string description: | Specifies the type of the transport document - `BOL` (Bill of Lading) - `SWB` (Sea Waybill) enum: - BOL - SWB ... (clipped 627 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: Missing validation: The new integer field lacks explicit constraints (e.g., minimum value, non-negative, monotonic rules) which may allow invalid edge cases like negative or zero revisions without defined error handling. Referred Code shippingInstructionsRevisionNumber: type: integer description: | The version number of the **Shipping Instructions** provided by the customer to ensure the carrier uses the most recent update when creating the **Transport Document**. This value is expected to increment by one with each **Shipping Instructions** update, with higher values representing newer versions. example: 1 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: Lacking constraints: The schema adds an external input field without minimum/format constraints or notes on authorization/immutability, which could permit invalid or insecure values for revision numbers. Referred Code shippingInstructionsRevisionNumber: type: integer description: | The version number of the **Shipping Instructions** provided by the customer to ensure the carrier uses the most recent update when creating the **Transport Document**. This value is expected to increment by one with each **Shipping Instructions** update, with higher values representing newer versions. example: 1 Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

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

[Copilot]

Pull request overview

This PR adds a shippingInstructionsRevisionNumber field to the Shipping Instructions API to enable version tracking. This ensures carriers use the most recent Shipping Instructions update when creating Transport Documents.

• Added shippingInstructionsRevisionNumber as an integer field with auto-incrementing capability
• Field added to three Shipping Instructions schema components: Create request, response, and base schema
• Includes descriptive documentation explaining version tracking behavior

Reviewed changes

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

File	Description
ebl/v3/EBL_v3.0.3.yaml	Added shippingInstructionsRevisionNumber field to CreateShippingInstructionsRequest, ShippingInstructions, and ShippingInstructionsResponse schemas with consistent description and example value
.stoplight/styleguide.json	Minor configuration update (not shown in diff)

---

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

[Copilot]

The shippingInstructionsRevisionNumber field lacks constraints. Consider adding minimum: 1 to ensure the revision number is always positive, as the description indicates it increments starting from 1.

Suggested change

	type: integer
	type: integer
	minimum: 1

[Copilot]

The field is not marked as required in the CreateShippingInstructionsRequest schema. If version tracking is essential for ensuring carriers use the correct version, consider whether this field should be required, or document the behavior when it's omitted.

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Use standard HTTP ETags for versioning Instead of adding a shippingInstructionsRevisionNumber field to the request body for versioning, use standard HTTP ETag and If-Match headers. This aligns with web standards for optimistic concurrency control. Examples: ebl/v3/EBL_v3.0.3.yaml [3058-3062] shippingInstructionsRevisionNumber: type: integer description: | The version number of the **Shipping Instructions** provided by the customer to ensure the carrier uses the most recent update when creating the **Transport Document**. This value is expected to increment by one with each **Shipping Instructions** update, with higher values representing newer versions. example: 1 ebl/v3/EBL_v3.0.3.yaml [3379-3383] shippingInstructionsRevisionNumber: type: integer description: | The version number of the **Shipping Instructions** provided by the customer to ensure the carrier uses the most recent update when creating the **Transport Document**. This value is expected to increment by one with each **Shipping Instructions** update, with higher values representing newer versions. example: 1 Solution Walkthrough: Before: # PUT /shipping-instructions/{id} # Body: { "shippingInstructionsRevisionNumber": 1, "transportDocumentReference": "...", "isElectronic": true, "isToOrder": true, // ... other fields } After: # PUT /shipping-instructions/{id} # Headers: # If-Match: "v1" # # Body: { "transportDocumentReference": "...", "isElectronic": true, "isToOrder": true, // ... other fields } Suggestion importance[1-10]: 7 __ Why: This is a valid, high-impact API design suggestion that proposes using a standard mechanism (ETag headers) for versioning instead of a custom payload field, which is a better practice for RESTful services.	Medium
General	Enforce positive revision number values Add a minimum: 1 constraint to the shippingInstructionsRevisionNumber field to enforce that it only accepts positive integer values, aligning with its documented purpose as an incrementing version number. ebl/v3/EBL_v3.0.3.yaml [3058-3062] shippingInstructionsRevisionNumber: type: integer description: | The version number of the **Shipping Instructions** provided by the customer to ensure the carrier uses the most recent update when creating the **Transport Document**. This value is expected to increment by one with each **Shipping Instructions** update, with higher values representing newer versions. example: 1 + minimum: 1 Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly infers from the field's description that its value should be positive and proposes adding a minimum: 1 constraint, which improves the API's data integrity.	Medium
More

[pedrocarvalhodcsa]

Seems good to me. Copilot has a question regarding negative values for the version, do you think that's good to include or unecessary?

[HenrikHL]

Seems good to me. Copilot has a question regarding negative values for the version, do you think that's good to include or unecessary?

I rather not put any restrictions on this - as it might turn up a carrier would like to use negative numbers.