CS 1.0: SD-2688: Add Departure and Arrival transportCallReference

[HenrikHL]

User description

SD-2688: CS Patch - PtoP - Feedback CMA: TransportCallReference for departure and for arrival

---

PR Type

Enhancement

---

Description

• Add transportCallReference property to Arrival and Departure objects

• Mark transportCallReference in Vessel-Transport and Barge-Transport as deprecated

• Update documentation to clarify precedence and usage of transport call references

• Minor whitespace and formatting corrections

---

Diagram Walkthrough

flowchart LR
  A["Arrival Object"] -->|"Add transportCallReference"| B["Transport Call Reference"]
  C["Departure Object"] -->|"Add transportCallReference"| B
  D["Vessel-Transport/Barge-Transport"] -->|"Deprecate transportCallReference"| E["Use Arrival/Departure instead"]
  B -->|"Takes precedence over"| D

Loading

File Walkthrough

	Relevant files
Enhancement	CS_v1.0.2.yaml Add and deprecate transportCallReference properties            cs/v1/CS_v1.0.2.yaml Add transportCallReference property to Arrival object with description and example Add transportCallReference property to Departure object with description and example Mark transportCallReference in Vessel-Transport as deprecated with migration guidance Mark transportCallReference in Barge-Transport as deprecated with migration guidance Update documentation to clarify that Arrival/Departure transportCallReference takes precedence Minor whitespace cleanup in documentation comments +27/-4
Configuration changes	styleguide.json Styleguide configuration updates                                                  .stoplight/styleguide.json Configuration file modified (insufficient token budget for detailed analysis) +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-2688 🟢 Add `transportCallReference` inside the **Departure** object. Add `transportCallReference` inside the **Arrival** object. Deprecate the current transportCallReference located on the leg-level transport object (Vessel-Transport/Barge-Transport) while still allowing it to be present for backwards compatibility. Clarify behavior/precedence when both the point-level (Arrival/Departure) and transport-level transportCallReference are provided (point-level should take precedence and transport-level should be ignored).
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
Update

Compliance status legend

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

[Copilot]

Pull request overview

This PR enhances the Commercial Schedules API by relocating the transportCallReference property from the transport-level objects (Vessel-Transport and Barge-Transport) to the more granular Arrival and Departure objects. This change provides better precision in identifying transport calls by allowing distinct references for arrival and departure events.

Key Changes:

• Added transportCallReference property to both Arrival and Departure objects with clear precedence rules
• Deprecated transportCallReference in Vessel-Transport and Barge-Transport objects with migration guidance
• Updated documentation to clarify the precedence hierarchy when multiple transport call references are present

Reviewed changes

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

File	Description
cs/v1/CS_v1.0.2.yaml	Added transportCallReference to Arrival and Departure objects; deprecated same property in Vessel-Transport and Barge-Transport with migration guidance
.stoplight/styleguide.json	Minor configuration update

---

💡 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
General	Clarify deprecation and precedence logic Clarify the deprecation notice for transportCallReference to specify that the new arrival and departure references individually take precedence over the old field, which can act as a fallback. cs/v1/CS_v1.0.2.yaml [1379-1382] description: | The unique reference for a transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. - **Deprecated:** Please use the `transportCallReference` (in **Departure** object) or `transportCallReference` (in **Arrival** object) in order to specify what the **TransportCall** is linked to. If provided in either `Arrival` or `Departure` object - this property must be ignored. + **Deprecated:** Please use `arrival.transportCallReference` for the arrival part of the transport call and `departure.transportCallReference` for the departure part. The `arrival.transportCallReference` takes precedence over this field for the arrival, and `departure.transportCallReference` takes precedence for the departure. This field may be used as a fallback if the specific arrival/departure references are not provided. Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies an ambiguity in the deprecation logic and proposes a clearer description, which improves the API specification and helps prevent implementation errors by consumers.	Medium
Update