BKG 2.0: SD-2733: Add Vessel-Voyage info per leg

[HenrikHL]

User description

SD-2733: Add vessel and voyage per leg in a Booking request

---

PR Type

Enhancement

---

Description

• Add departingVesselVoyage object to transport leg specification

• Include vessel details: name, flag, IMO number, call sign

• Include voyage identifiers: carrier service code, universal service reference

• Include export voyage references: carrier and universal voyage numbers

---

Diagram Walkthrough

flowchart LR
  A["Transport Leg"] -->|"adds"| B["departingVesselVoyage Object"]
  B -->|"contains"| C["Vessel Details"]
  B -->|"contains"| D["Service Identifiers"]
  B -->|"contains"| E["Voyage References"]
  C -->|"includes"| F["Name, Flag, IMO, Call Sign"]
  D -->|"includes"| G["Carrier Service Code, USR"]
  E -->|"includes"| H["Export Voyage Numbers"]

Loading

File Walkthrough

	Relevant files
Enhancement	BKG_v2.0.4.yaml Add departingVesselVoyage object with vessel voyage details bkg/v2/BKG_v2.0.4.yaml Added new departingVesselVoyage object schema with vessel and voyage properties Includes vessel identification fields: vesselName, vesselFlag, vesselIMONumber, vesselCallSign Includes service identifiers: carrierServiceCode, universalServiceReference Includes export voyage references: carrierExportVoyageNumber, universalExportVoyageReference All properties include detailed descriptions, validation patterns, and examples +72/-0
Configuration changes	styleguide.json Update styleguide configuration                                                    .stoplight/styleguide.json Minor configuration changes to styleguide +1/-1

---

[qodo-code-review]

PR Compliance Guide 🔍

(Compliance updated until commit 954246a)

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-2733 🟢 Add a per-leg vessel/voyage object (e.g., departingVesselVoyage) to the booking request schema. Include vessel details per leg: vessel name, flag, IMO number, and call sign. Include voyage/service identifiers per leg: carrier service code and universal service reference. Include export voyage references per leg: carrier export voyage number and universal export voyage reference. Update the Booking API in a backward-compatible way to allow providing complete routing details for connected legs (end-to-end routing), not only the vessel associated with POL. ⚪ Confirm end-to-end behavior: the API implementation, documentation rendering, and client/server validation accept and correctly interpret multiple legs with departingVesselVoyage (not just schema presence), including real-world examples from Place of Receipt to Place of Delivery. Confirm backward compatibility in practice for existing consumers (e.g., generated clients, validators, and any downstream mapping) when departingVesselVoyage is omitted, and confirm the locationTypeCode='ROU' constraint is enforced/handled as intended.
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 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: Unenforced constraint: The schema documents that departingVesselVoyage must not be used with locationTypeCode='ROU', but this mutual exclusivity is not enforced via a JSON Schema constraint (e.g., oneOf/not), allowing invalid input to pass validation. Referred Code departingVesselVoyage: type: object title: Vessel Voyage description: | Vessel and voyage details of a transport leg. **Note:** This property is not to be used in combination with `locationTypeCode='ROU'`. properties: 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 55fbf3d

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡	🎫 #SD-2733 🟢 Ensure that when multiple routing legs are requested, vessel/voyage information can be included beyond only the leg associated with the Port of Loading (i.e., per transport leg / connected legs). Define and document the API/schema changes needed to enable inclusion of full transport details from Place of Receipt to Place of Delivery in the Booking request. ⚪ Update the Booking API in a backward-compatible way to support providing complete end-to-end routing details (multiple legs) in a Booking request.
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 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: Passed Learn more about managing compliance generic rules or creating your own custom rules

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Generalize the new transport object Rename the new departingVesselVoyage object to a more generic name like departingTransport. Add a transportMode field to support different transport types, making the API more extensible for multi-modal shipments. Examples: bkg/v2/BKG_v2.0.4.yaml [5094-5165] departingVesselVoyage: type: object title: Vessel Voyage description: | Vessel and voyage details of a transport leg. **Note:** This property is not to be used in combination with `locationTypeCode='ROU'`. properties: vesselName: type: string ... (clipped 62 lines) Solution Walkthrough: Before: # bkg/v2/BKG_v2.0.4.yaml ShipmentLocation: properties: location: ... locationTypeCode: ... departingVesselVoyage: # Specific to sea transport type: object properties: vesselName: ... vesselIMONumber: ... carrierExportVoyageNumber: ... # ... other vessel/voyage specific fields After: # bkg/v2/BKG_v2.0.4.yaml ShipmentLocation: properties: location: ... locationTypeCode: ... departingTransport: # Generic transport object type: object properties: transportMode: # Discriminator for transport type type: string enum: [SEA, RAIL, TRUCK] # Fields below would be conditional on transportMode='SEA' vesselName: ... vesselIMONumber: ... # ... other mode-specific fields can be added later Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a design limitation where the new departingVesselVoyage object is too specific, and proposes a significant architectural improvement for future multi-modal extensibility.	Medium
Possible issue	Correct IMO number validation to 7-digits Correct the vesselIMONumber validation to strictly enforce a 7-digit numeric format by changing the pattern to ^\d{7}$ and setting minLength and maxLength to 7. bkg/v2/BKG_v2.0.4.yaml [5115-5122] vesselIMONumber: type: string - pattern: ^\d{7,8}$ + pattern: ^\d{7}$ minLength: 7 - maxLength: 8 + maxLength: 7 description: | The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel example: '9321483' Apply / Chat Suggestion importance[1-10]: 8 __ Why: This suggestion corrects an error in the schema for vesselIMONumber, which incorrectly allows 8 digits. Aligning the validation with the 7-digit IMO standard is a critical fix for data integrity.	Medium
	✅ Enforce stricter validation for vessel flag Suggestion Impact: The commit updated vesselFlag to include minLength: 2 and a regex pattern (^[A-Z]{2}$), tightening validation as suggested. It also revised the description text. code diff: vesselFlag: type: string + pattern: ^[A-Z]{2}$ + minLength: 2 maxLength: 2 description: | - The national flag of the country under which a vessel is registered, indicated by the 2-character code defined in [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en). + The flag of the nation whose laws the vessel is registered under. This is the [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) two-letter country code. example: NL Enforce stricter validation for vesselFlag by setting minLength to 2 and adding a pattern ^[A-Z]{2}$ to ensure it is a 2-character uppercase code. bkg/v2/BKG_v2.0.4.yaml [5109-5114] vesselFlag: type: string + minLength: 2 maxLength: 2 + pattern: '^[A-Z]{2}$' description: | The national flag of the country under which a vessel is registered, indicated by the 2-character code defined in [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en). example: NL [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that the validation for vesselFlag is too permissive and proposes stricter rules (minLength, maxLength, and a pattern) that align with the field's description, thus improving data integrity.	Medium
	Require IMO number Make the vesselIMONumber a required field within the departingVesselVoyage object to ensure a key identifier is always provided. bkg/v2/BKG_v2.0.4.yaml [5094-5095] departingVesselVoyage: type: object + required: + - vesselIMONumber Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion makes a reasonable assumption that vesselIMONumber should be a required field for identification, improving the robustness of the API contract.	Low
General	Escape regex in the description text Escape the backslash in the regex pattern within the description for universalExportVoyageReference to ensure it is rendered correctly. bkg/v2/BKG_v2.0.4.yaml [5155-5165] universalExportVoyageReference: type: string pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ minLength: 5 maxLength: 5 description: | - A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]` - `2 digits` for the year - `2 alphanumeric characters` for the sequence number of the voyage - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). example: 2103N Apply / Chat Suggestion importance[1-10]: 3 __ Why: This is a minor but correct suggestion to improve the clarity of the documentation by properly escaping a backslash in a regex pattern within a description string.	Low
Update

[Copilot]

Pull request overview

This PR adds vessel and voyage information to transport legs in booking requests, enabling tracking of specific vessels and voyages per leg rather than only at the overall booking level.

Changes:

• Added departingVesselVoyage object to transport leg specification with vessel details and voyage identifiers
• Included comprehensive validation patterns and examples for all vessel/voyage fields

Reviewed changes

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

File	Description
bkg/v2/BKG_v2.0.4.yaml	Adds departingVesselVoyage object schema with vessel identification, service identifiers, and voyage reference properties
.stoplight/styleguide.json	Minor configuration update

---

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

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

---

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

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[palatsangeetha]

Suggested change

	The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel
	The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel.

[palatsangeetha]

same minor change, (.) at the end as above. To be consistent with other descriptions.