OVS 3.0: SD-3527: Improve backward compatibility

[HenrikHL]

SD-3527: OMIT WaterWays when communicating with an earlier consumer

[qodo-code-review]

PR Summary by Qodo

Specify OVS 3.0.3 waterway backward compatibility

📝 Documentation ✨ Enhancement 🕐 10-20 Minutes

AI Description

• Require providers to omit waterway TransportCalls for consumers using OVS v3.0.2 or earlier.
• Apply the rule to both response scopes and treat missing or legacy version headers as v3.0.0.
• Preserve remaining call order without disguising waterway calls as another location type.

Diagram

graph TD
  Header["API-Version header"] --> Gate{"Supports WWAY?"} -->|No| Omit["Omit WWAY calls"] --> Response["Schedule response"]
  Gate -->|Yes| Retain["Retain WWAY calls"] --> Response

Loading

High-Level Assessment

Version-gated omission in the existing endpoint is appropriate and follows its established consumer-version compatibility pattern. Separate version-specific response schemas would duplicate the contract without changing the required provider behavior.

Files changed (2) +15 / -2

Documentation (2) +15 / -2

OVS_v3.0.3.yamlDefine version-gated omission of waterway TransportCalls +14/-2

Define version-gated omission of waterway TransportCalls

• Requires providers to omit entire WWAY TransportCalls for consumers earlier than v3.0.3, regardless of response scope. Clarifies handling of missing or legacy API-Version headers, prohibits location-type substitution, and requires the remaining calls to retain their order.

ovs/v3/OVS_v3.0.3.yaml

README.mdRecord waterway compatibility rule in release notes +1/-0

Record waterway compatibility rule in release notes

• Adds the v3.0.3 release-note requirement to omit waterway TransportCalls for older consumers, including those with missing or legacy version headers, in both response scopes.

ovs/v3/README.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

1. Pilot timestamp version guidance is lost ✓ Resolved

Description

The revised API-Version description uses “for this purpose” to limit the absent-header and legacy
3 fallback to the waterway TransportCall rule, rather than also applying it to the existing PBPL
timestamp rule. When either legacy header form is used, providers lack an explicit basis to treat
the consumer as v3.0.0 for the timestamp rule and may include a PBPL timestamp.

Code

ovs/v3/OVS_v3.0.3.yaml[253]

+            For backward compatibility, an absent header or the value `3` **MUST** be treated as a consumer implementing v3.0.0 for this purpose. Providers **MUST NOT** include waterway TransportCalls unless the consumer version establishes support for them.

Evidence

The previous line 243 applied the v3.0.0 fallback to the preceding compatibility rule, and rule 5
requires that existing header description to be retained. The replacement at line 253 confines the
fallback to “this purpose” after the new waterway rule, while line 247 still requires omission of
PBPL timestamps for consumers below v3.0.2; the vessel compatibility descriptions explicitly
identify blank or 3 headers as v3.0.0 requests.

Document waterway backward compatibility
ovs/v3/OVS_v3.0.3.yaml[243-253]
ovs/v3/OVS_v3.0.3.yaml[380-399]
ovs/v3/OVS_v3.0.3.yaml[848-857]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The revised `API-Version` header description restricts the absent-header and `3`-header fallback to waterway calls, leaving its application to the existing `PBPL` timestamp compatibility rule unclear.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[243-253]

## Recommended Fix
State that an absent `API-Version` request header or a value of `3` is treated as v3.0.0 for both the `PBPL` timestamp rule and the new waterway TransportCall rule. Preserve the existing timestamp restriction.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Tickets: 🎫 OMIT WaterWays when communicating with an earlier consumer

Review mode: ⚖️ Balanced: This is a small but contract-affecting API specification change that alters backward-compatibility behavior and request filtering semantics.

Tip of the day

💡 Did you know, you can keep summaries lean with Findings visible per group, which tucks the rest behind a View link

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit a29bcf4

Results up to commit 2c44ab0 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Pilot timestamp version guidance is lost ✓ Resolved

Description

The revised API-Version description uses “for this purpose” to limit the absent-header and legacy
3 fallback to the waterway TransportCall rule, rather than also applying it to the existing PBPL
timestamp rule. When either legacy header form is used, providers lack an explicit basis to treat
the consumer as v3.0.0 for the timestamp rule and may include a PBPL timestamp.

Code

ovs/v3/OVS_v3.0.3.yaml[253]

+            For backward compatibility, an absent header or the value `3` **MUST** be treated as a consumer implementing v3.0.0 for this purpose. Providers **MUST NOT** include waterway TransportCalls unless the consumer version establishes support for them.

Evidence

The previous line 243 applied the v3.0.0 fallback to the preceding compatibility rule, and rule 5
requires that existing header description to be retained. The replacement at line 253 confines the
fallback to “this purpose” after the new waterway rule, while line 247 still requires omission of
PBPL timestamps for consumers below v3.0.2; the vessel compatibility descriptions explicitly
identify blank or 3 headers as v3.0.0 requests.

Document waterway backward compatibility
ovs/v3/OVS_v3.0.3.yaml[243-253]
ovs/v3/OVS_v3.0.3.yaml[380-399]
ovs/v3/OVS_v3.0.3.yaml[848-857]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The revised `API-Version` header description restricts the absent-header and `3`-header fallback to waterway calls, leaving its application to the existing `PBPL` timestamp compatibility rule unclear.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[243-253]

## Recommended Fix
State that an absent `API-Version` request header or a value of `3` is treated as v3.0.0 for both the `PBPL` timestamp rule and the new waterway TransportCall rule. Preserve the existing timestamp restriction.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[HenrikHL]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit a29bcf4

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation and API specification consistently define the intended compatibility behavior.

Review effort: Balanced
Findings: None

What changed in this PR

Adds backward-compatibility requirements for waterway transport calls when serving pre-v3.0.3 consumers.

Changes:

• Requires WWAY transport calls to be removed before filtering and pagination.
• Defines behavior for absent and legacy API-Version headers.
• Documents the compatibility rule in the release notes and schema.

File	Description
ovs/​v3/​README.md	Records the backward-compatibility requirement.
ovs/​v3/​OVS_v3.0.3.yaml	Specifies version detection and omission of unsupported waterway calls.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.