OVS 3.0: SD-3052: Add 'responseScope' to limit response

[HenrikHL]

SD-3052: Add responseScope filter allow results to only include partial voyages

[qodo-code-review]

Review Summary by Qodo

Add responseScope parameter to limit voyage response scope

✨ Enhancement

Walkthroughs

Description

• Add responseScope query parameter to limit response scope
• Support FULL_VOYAGE (default) and MATCHED_CALLS response modes
• Allow partial voyage returns when filtering by specific ports
• Update API documentation with new parameter behavior and examples

Diagram

flowchart LR
  A["GET /v3/service-schedules"] -->|"responseScope parameter"| B["Response Scope Options"]
  B -->|"FULL_VOYAGE default"| C["Return entire matched voyages"]
  B -->|"MATCHED_CALLS"| D["Return only matched transportCalls"]
  C -->|"Filter: UNLocationCode=DEHAM"| E["All ports in matching voyages"]
  D -->|"Filter: UNLocationCode=DEHAM"| F["Only DEHAM transportCalls"]

Loading

File Changes

1. ovs/v3/OVS_v3.0.2.yaml ✨ Enhancement +19/-1

Add responseScope parameter for flexible voyage filtering

• Added responseScope query parameter with two possible values: FULL_VOYAGE (default) and
 MATCHED_CALLS
• Updated endpoint description to clarify default behavior returns entire voyages unless
 responseScope specifies otherwise
• Added v3.0.2 release note explaining partial voyage behavior when using MATCHED_CALLS
• Included examples showing response differences between FULL_VOYAGE and MATCHED_CALLS modes

ovs/v3/OVS_v3.0.2.yaml

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Conflicting voyage scope docs 🐞 Bug ≡ Correctness

Description

responseScope=MATCHED_CALLS is documented to return only matched transportCalls, but existing
filter parameter descriptions (e.g., UNLocationCode, facilitySMDGCode, startDate, endDate)
still state they return **entire Voyages**, making the OpenAPI contract contradictory. This will
mislead client implementations and testers about what the endpoint returns when responseScope is
used.

Code

ovs/v3/OVS_v3.0.2.yaml[R46-52]

+        The number of service schedules in the list can be narrowed down by providing filter parameters. The resulting payload will always include **entire voyage(s) being matched**, unless otherwise specified (see `responseScope` query parameter). This means that even though a filter only matches a single `Port` in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included.
        
        An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`.
+
+        **Note as of v3.0.2:** If `responseScope` is used with the `MATCHED_CALLS` value then only **partial voyage(s) will potentially be returned**. This means that if a filter only matches a single `Port` (`UNLocationCode`) in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **only matched transportCalls** are returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **matched transportCalls** where either one (or both) match the filter are included.
+        
+        An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **transportCalls matching `DEHAM`** would be included.

Evidence

The spec now explicitly documents that responseScope=MATCHED_CALLS can return only matched
transportCalls (partial voyages), but multiple filter parameters still describe results as always
containing "entire Voyages", which cannot be simultaneously true under the documented behavior.

ovs/v3/OVS_v3.0.2.yaml[46-52]
ovs/v3/OVS_v3.0.2.yaml[133-171]
ovs/v3/OVS_v3.0.2.yaml[175-188]

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 new `responseScope` feature allows partial voyages (`MATCHED_CALLS`), but several existing query parameter descriptions still claim that using those filters will return *entire* voyages. This creates an internal contradiction in the OpenAPI spec.

## Issue Context
The endpoint description now mentions `responseScope` can change behavior, but parameter-level docs still describe the legacy/full-voyage behavior unconditionally.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.2.yaml[133-171]

### Suggested change
Update the descriptions for `UNLocationCode`, `facilitySMDGCode`, `startDate`, and `endDate` (and any similar text) to either:
- remove unconditional "entire voyage" wording, or
- explicitly qualify it with “when `responseScope=FULL_VOYAGE` (default)”, and describe the `MATCHED_CALLS` behavior consistently.

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

---

2. Unconstrained responseScope values 🐞 Bug ⚙ Maintainability

Description

The responseScope parameter documents two allowed values (FULL_VOYAGE, MATCHED_CALLS) but its
OpenAPI schema is an unconstrained string, so generated clients and request validators cannot
enforce the allowed set. This increases the chance of client-side typos and inconsistent
implementations slipping through until runtime/server-side validation.

Code

ovs/v3/OVS_v3.0.2.yaml[R184-188]

+          schema:
+            type: string
+            maxLength: 30
+            default: FULL_VOYAGE
+            example: MATCHED_CALLS

Evidence

The parameter description lists exactly two possible values, but the schema only specifies `type:
string (no enum`), so the allowed values are not machine-enforceable from the OpenAPI definition.

ovs/v3/OVS_v3.0.2.yaml[175-188]

Agent prompt

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

## Issue description
`responseScope` is described as having two possible values, but the schema does not include an `enum`, so tooling/codegen will treat it as a free-form string.

## Issue Context
This is primarily an API contract/schema quality issue: it affects client generation and client-side validation (server-side validation behavior is not expressed here).

## Fix Focus Areas
- ovs/v3/OVS_v3.0.2.yaml[175-188]

### Suggested change
Add an enum to the parameter schema:
```yaml
schema:
 type: string
 enum:
   - FULL_VOYAGE
   - MATCHED_CALLS
 default: FULL_VOYAGE
 example: MATCHED_CALLS
```
Keep `maxLength` only if it is required by your API design rules.

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

---

[qodo-code-review]

1. Conflicting voyage scope docs 🐞 Bug ≡ Correctness

responseScope=MATCHED_CALLS is documented to return only matched transportCalls, but existing
filter parameter descriptions (e.g., UNLocationCode, facilitySMDGCode, startDate, endDate)
still state they return **entire Voyages**, making the OpenAPI contract contradictory. This will
mislead client implementations and testers about what the endpoint returns when responseScope is
used.

Agent Prompt

## Issue description
The new `responseScope` feature allows partial voyages (`MATCHED_CALLS`), but several existing query parameter descriptions still claim that using those filters will return *entire* voyages. This creates an internal contradiction in the OpenAPI spec.

## Issue Context
The endpoint description now mentions `responseScope` can change behavior, but parameter-level docs still describe the legacy/full-voyage behavior unconditionally.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.2.yaml[133-171]

### Suggested change
Update the descriptions for `UNLocationCode`, `facilitySMDGCode`, `startDate`, and `endDate` (and any similar text) to either:
- remove unconditional "entire voyage" wording, or
- explicitly qualify it with “when `responseScope=FULL_VOYAGE` (default)”, and describe the `MATCHED_CALLS` behavior consistently.

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

[Copilot]

Pull request overview

Adds a responseScope query parameter to OVS service schedules so consumers can request either full matched voyages or only matched transport calls.

Changes:

• Updates endpoint description to explain default full-voyage behavior and the new partial-voyage behavior.
• Adds the responseScope query parameter with documented values FULL_VOYAGE and MATCHED_CALLS.

---

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

[emiliodcsa]

i like that qodo folk helping with the review.

[emiliodcsa]

looks good to me.