OVS 3.0: SD-2234: Add WaterWays to schedules

[HenrikHL]

SD-2234: Implementation of waterways (canals & straits)

[qodo-code-review]

PR Summary by Qodo

Add waterway locations to OVS 3.0.3 schedules

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Adds WWAY-discriminated waterway locations to vessel schedule transport calls.
• Defines optional SMDG entry points and waterway-specific timestamp semantics.
• Generalizes schedule and filter documentation from ports to transport-call locations.

Diagram

classDiagram
class VesselSchedule
class TransportCall
class LocationUnion
class Timestamp
class UNLocation
class FacilityLocation
class AddressLocation
class WaterwayLocation
VesselSchedule "1" *-- "*" TransportCall : contains
TransportCall "1" *-- "1" LocationUnion : location
TransportCall "1" *-- "*" Timestamp : timestamps
LocationUnion <|-- UNLocation : UNLO
LocationUnion <|-- FacilityLocation : FACS
LocationUnion <|-- AddressLocation : ADDR
LocationUnion <|-- WaterwayLocation : WWAY

Loading

High-Level Assessment

Extending the existing discriminated location union is the best approach because waterways remain ordered TransportCalls and reuse existing voyage, filtering, and timestamp structures. A separate waterway-call collection would fragment schedule sequencing and duplicate established semantics.

Files changed (1) +143 / -27

Enhancement (1) +143 / -27

OVS_v3.0.3.yamlAdd SMDG waterway locations to the OVS schedule contract +143/-27

Add SMDG waterway locations to the OVS schedule contract

• Adds 'WaterwaySMDGLocation' as the 'WWAY' discriminator variant, requiring a UN/LOCODE and optionally identifying an SMDG waterway entry point. Clarifies transport-call references, filters, timestamps, and non-applicable port fields for waterways, while constraining existing discriminator values and updating the changelog link.

ovs/v3/OVS_v3.0.3.yaml

[qodo-code-review]

Code Review by Qodo

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

1. Waterway events still default to berths ✗ Dismissed 📎 Requirement gap ≡ Correctness

Description

Timestamp.facilityTypeCode retains the unconditional schema-level default: BRTH even though its
new description says that default must not be inferred when locationType is WWAY. Because every
TransportCall uses the shared timestamp schema, omitting this optional property on a waterway call
lets schema-driven consumers materialize a berth value despite the contract stating that waterways
have no berthing.

Code

ovs/v3/OVS_v3.0.3.yaml[R831-834]

+            This property is not applicable when the containing TransportCall has `location.locationType` equal to `WWAY`. For a WWAY TransportCall:
+
+            - the API provider **SHOULD** omit `facilityTypeCode`;
+            - the `BRTH` default does not apply and **MUST NOT** be inferred; and

Evidence

Every TransportCall, including those whose location discriminator selects WaterwaySMDGLocation,
uses the shared Timestamp schema. That schema marks facilityTypeCode as optional but retains an
unconditional default: BRTH at line 821, while the added text at lines 831–834 says the default
must not apply to WWAY; this machine-readable contradiction also fails compliance rule 6's
requirement to update the default appropriately for waterways.

Represent WWAY as a Non-Berthing, Non-Cargo-Operation Location
ovs/v3/OVS_v3.0.3.yaml[818-837]
ovs/v3/OVS_v3.0.3.yaml[483-499]
ovs/v3/OVS_v3.0.3.yaml[540-543]
ovs/v3/OVS_v3.0.3.yaml[818-842]

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 shared `Timestamp.facilityTypeCode` schema declares an unconditional `default: BRTH`, contradicting the newly added rule that this default must not be inferred for `WWAY` transport calls.

## Issue Context
Every `TransportCall` uses the shared `Timestamp` schema, including calls whose location discriminator selects `WaterwaySMDGLocation`. Because the machine-readable default cannot vary based on the containing transport call's location type, remove it or restructure the schemas so the berth default applies only to port or facility timestamps and cannot be materialized for waterway timestamps, while preserving validation and documentation for both location categories.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[483-499]
- ovs/v3/OVS_v3.0.3.yaml[818-842]

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

---

2. Clients lose every request parameter ✓ Resolved 🐞 Bug ≡ Correctness

Description

parameters: is indented at the content level of the description: | scalar, so YAML parses it and
every parameter definition through API-Version as description text rather than an operation field.
Tooling generated from v3.0.3 therefore exposes the GET operation without its query or header
parameters, including all filters, pagination controls, and the version header.

Code

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

+        parameters:

Evidence

The description block begins at line 40, and its content uses the same indentation as the newly
added parameters: line at line 72. The existing responses: field finally dedents at line 239, so
the intervening parameter declarations are consumed by the description scalar instead of forming an
OpenAPI parameters array.

ovs/v3/OVS_v3.0.3.yaml[40-73]
ovs/v3/OVS_v3.0.3.yaml[232-240]

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 GET operation's `parameters` key is currently inside the block-scalar indentation of `description`, causing every request parameter to become description text.

## Issue Context
Dedent `parameters:` to the same operation-field level as `description:` and `responses:` while retaining the parameter list beneath it.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[40-73]

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

---

3. Waterway cargo limits stay undocumented ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

WaterwaySMDGLocation.description documents identification precision but never states that loading
and discharge operations do not occur at the represented location. Consumers reading the newly added
waterway schema therefore receive a non-berthing constraint elsewhere but no equivalent
cargo-operation boundary for any WWAY call.

Code

ovs/v3/OVS_v3.0.3.yaml[R699-702]

+      description: |
+        A waterway location identified using the [**SMDG Waterway Code List**](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/).
+
+        `UNLocationCode` identifies the waterway. When `waterwaySMDGEntryPointCode` is provided, the combination of the two values identifies a specific point on the waterway.

Evidence

Compliance rule 6 requires the API and documentation to state that waterway locations have no load
or discharge operations. The complete added WaterwaySMDGLocation description only explains
waterway identification and point precision, while the only waterway operational restriction
elsewhere covers berthing.

Represent WWAY as a Non-Berthing, Non-Cargo-Operation Location
ovs/v3/OVS_v3.0.3.yaml[696-704]
ovs/v3/OVS_v3.0.3.yaml[831-837]

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 waterway schema does not state that `WWAY` locations have no loading or discharge operations.

## Issue Context
The specification separately documents that waterways have no vessel berthing, but compliance rule 6 also requires the cargo-operation restriction to be explicit.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[696-704]

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

---

4. Blank waterway points pass validation 🐞 Bug ≡ Correctness ⭐ New

Description

waterwaySMDGEntryPointCode accepts an empty string whenever the property is present, even though
the description treats its presence as identifying a specific waterway point. A payload can
therefore provide waterwaySMDGEntryPointCode: "" and be interpreted inconsistently by consumers
that distinguish an omitted code from a supplied point code.

Code

ovs/v3/OVS_v3.0.3.yaml[R743-745]

+            This property is optional. When omitted, the location identifies the waterway but not a specific waterway point.
+
+            Valid values are published in the [SMDG Waterway Code List](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/).

Evidence

The new description explicitly says that omitting the property identifies only the waterway and that
valid values are published in the SMDG list, while the property schema has no minimum length or
non-empty pattern. JSON Schema string constraints therefore allow an explicitly supplied empty
string.

ovs/v3/OVS_v3.0.3.yaml[735-745]

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 optional `waterwaySMDGEntryPointCode` property can be supplied as an empty string because the schema only limits its maximum length. This violates the documented distinction between an omitted code, which identifies only the waterway, and a supplied code, which identifies a specific point.

## Issue Context
Keep the property optional, but reject empty values when it is present. Use the validation constraints already used by the schema and preserve the published SMDG code-list semantics.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[735-745]

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

---

5. Readers get the response hierarchy wrong ✓ Resolved 🐞 Bug ≡ Correctness

Description

GET /v3/service-schedules says that Vessel is at the top of the response hierarchy even though
the response root contains ServiceSchedule objects, each of which contains vesselSchedules.
Consumers using this rewritten operation description to map the payload will expect the service and
vessel levels in the opposite order from the schema.

Code

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

+        The result is `Vessel-Centric`. This means that the `Vessel` is at the top of the response hierarchy. A service is a hierarchical structure with the following elements:

Evidence

The revised operation description places vessels at the top while immediately saying services
contain vessels. The response schema is an array of ServiceSchedule, and that schema owns the
nested vesselSchedules property.

ovs/v3/OVS_v3.0.3.yaml[43-45]
ovs/v3/OVS_v3.0.3.yaml[258-261]
ovs/v3/OVS_v3.0.3.yaml[312-342]

Agent prompt

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

## Issue description
Correct the endpoint description so it reflects the actual response hierarchy: a root array of service schedules, each containing vessel schedules.

## Issue Context
The current prose calls the response vessel-centric and places `Vessel` at the top, while the OpenAPI response schema places `ServiceSchedule` objects at the root and nests `vesselSchedules` inside them.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[43-45]
- ovs/v3/OVS_v3.0.3.yaml[258-261]
- ovs/v3/OVS_v3.0.3.yaml[312-342]

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

---

6. Users see a placeholder release date ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

README.md publishes the v3.0.3 changelog heading with the literal text RELEASE DATE instead of
an issued date. Anyone following the newly fixed v3.0.3 changelog link encounters unfinished release
metadata while every other stable v3 release is dated.

Code

ovs/v3/README.md[7]

+<a name="v303"></a>[Release v3.0.3 (RELEASE DATE)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3)

Evidence

The v3.0.3 entry contains an explicit placeholder, whereas the adjacent v3.0.2 and v3.0.1 stable
release headings contain concrete dates.

ovs/v3/README.md[7-7]
ovs/v3/README.md[19-28]

Agent prompt

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

## Issue description
Replace the literal `RELEASE DATE` placeholder in the v3.0.3 changelog heading with the actual issue date.

## Issue Context
The new changelog anchor is now the destination linked by the specification, but its heading still contains draft metadata unlike the existing stable release entries.

## Fix Focus Areas
- ovs/v3/README.md[7-7]
- ovs/v3/README.md[19-28]

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

---

View medium (1)

7. The changelog link has no destination ✓ Resolved 🐞 Bug ≡ Correctness

Description

The revised changelog URL targets #v303, but the linked ovs/v3/README.md has no matching anchor
or 3.0.3 release section. Users following the specification's changelog link remain at the README
rather than reaching release notes for this version.

Code

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

+    For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ovs/v3#v303). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us).

Evidence

The specification advertises #v303, while the README begins its release history at the v302
anchor and proceeds directly to v3.0.1. There is no target for the newly introduced fragment.

ovs/v3/OVS_v3.0.3.yaml[15-20]
ovs/v3/README.md[1-16]

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 specification links to a v3.0.3 changelog anchor that does not exist in the OVS README.

## Issue Context
Add the corresponding v3.0.3 release entry and `v303` anchor, or point the specification at an existing valid destination.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[15-20]
- ovs/v3/README.md[1-16]

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

---

Context sources

✅ Tickets: 🎫 Patch - OVS 3.0.3 - Implementation of waterways (canals & straits) codes in the standards using SMDG upcoming codes/structure

Review mode: 🚀 Fast: This is a small, localized OpenAPI YAML wording/description update with no structural or behavioral schema changes.

Tip of the day

💡 Did you know, you can tweak Display preferences with a live preview to see your comment before it ships

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit de4a6b5

Results up to commit 286404f ⚖️ Balanced

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

1. Waterway cargo limits stay undocumented ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

WaterwaySMDGLocation.description documents identification precision but never states that loading
and discharge operations do not occur at the represented location. Consumers reading the newly added
waterway schema therefore receive a non-berthing constraint elsewhere but no equivalent
cargo-operation boundary for any WWAY call.

Code

ovs/v3/OVS_v3.0.3.yaml[R699-702]

+      description: |
+        A waterway location identified using the [**SMDG Waterway Code List**](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/).
+
+        `UNLocationCode` identifies the waterway. When `waterwaySMDGEntryPointCode` is provided, the combination of the two values identifies a specific point on the waterway.

Evidence

Compliance rule 6 requires the API and documentation to state that waterway locations have no load
or discharge operations. The complete added WaterwaySMDGLocation description only explains
waterway identification and point precision, while the only waterway operational restriction
elsewhere covers berthing.

Represent WWAY as a Non-Berthing, Non-Cargo-Operation Location
ovs/v3/OVS_v3.0.3.yaml[696-704]
ovs/v3/OVS_v3.0.3.yaml[831-837]

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 waterway schema does not state that `WWAY` locations have no loading or discharge operations.

## Issue Context
The specification separately documents that waterways have no vessel berthing, but compliance rule 6 also requires the cargo-operation restriction to be explicit.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[696-704]

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

---

2. Clients lose every request parameter ✓ Resolved 🐞 Bug ≡ Correctness

Description

parameters: is indented at the content level of the description: | scalar, so YAML parses it and
every parameter definition through API-Version as description text rather than an operation field.
Tooling generated from v3.0.3 therefore exposes the GET operation without its query or header
parameters, including all filters, pagination controls, and the version header.

Code

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

+        parameters:

Evidence

The description block begins at line 40, and its content uses the same indentation as the newly
added parameters: line at line 72. The existing responses: field finally dedents at line 239, so
the intervening parameter declarations are consumed by the description scalar instead of forming an
OpenAPI parameters array.

ovs/v3/OVS_v3.0.3.yaml[40-73]
ovs/v3/OVS_v3.0.3.yaml[232-240]

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 GET operation's `parameters` key is currently inside the block-scalar indentation of `description`, causing every request parameter to become description text.

## Issue Context
Dedent `parameters:` to the same operation-field level as `description:` and `responses:` while retaining the parameter list beneath it.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[40-73]

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

---

3. Waterway events still default to berths ✗ Dismissed 📎 Requirement gap ≡ Correctness

Description

Timestamp.facilityTypeCode retains the unconditional schema-level default: BRTH even though its
new description says that default must not be inferred when locationType is WWAY. Because every
TransportCall uses the shared timestamp schema, omitting this optional property on a waterway call
lets schema-driven consumers materialize a berth value despite the contract stating that waterways
have no berthing.

Code

ovs/v3/OVS_v3.0.3.yaml[R831-834]

+            This property is not applicable when the containing TransportCall has `location.locationType` equal to `WWAY`. For a WWAY TransportCall:
+
+            - the API provider **SHOULD** omit `facilityTypeCode`;
+            - the `BRTH` default does not apply and **MUST NOT** be inferred; and

Evidence

Every TransportCall, including those whose location discriminator selects WaterwaySMDGLocation,
uses the shared Timestamp schema. That schema marks facilityTypeCode as optional but retains an
unconditional default: BRTH at line 821, while the added text at lines 831–834 says the default
must not apply to WWAY; this machine-readable contradiction also fails compliance rule 6's
requirement to update the default appropriately for waterways.

Represent WWAY as a Non-Berthing, Non-Cargo-Operation Location
ovs/v3/OVS_v3.0.3.yaml[818-837]
ovs/v3/OVS_v3.0.3.yaml[483-499]
ovs/v3/OVS_v3.0.3.yaml[540-543]
ovs/v3/OVS_v3.0.3.yaml[818-842]

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 shared `Timestamp.facilityTypeCode` schema declares an unconditional `default: BRTH`, contradicting the newly added rule that this default must not be inferred for `WWAY` transport calls.

## Issue Context
Every `TransportCall` uses the shared `Timestamp` schema, including calls whose location discriminator selects `WaterwaySMDGLocation`. Because the machine-readable default cannot vary based on the containing transport call's location type, remove it or restructure the schemas so the berth default applies only to port or facility timestamps and cannot be materialized for waterway timestamps, while preserving validation and documentation for both location categories.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[483-499]
- ovs/v3/OVS_v3.0.3.yaml[818-842]

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

---

4. The changelog link has no destination ✓ Resolved 🐞 Bug ≡ Correctness

Description

The revised changelog URL targets #v303, but the linked ovs/v3/README.md has no matching anchor
or 3.0.3 release section. Users following the specification's changelog link remain at the README
rather than reaching release notes for this version.

Code

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

+    For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ovs/v3#v303). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us).

Evidence

The specification advertises #v303, while the README begins its release history at the v302
anchor and proceeds directly to v3.0.1. There is no target for the newly introduced fragment.

ovs/v3/OVS_v3.0.3.yaml[15-20]
ovs/v3/README.md[1-16]

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 specification links to a v3.0.3 changelog anchor that does not exist in the OVS README.

## Issue Context
Add the corresponding v3.0.3 release entry and `v303` anchor, or point the specification at an existing valid destination.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[15-20]
- ovs/v3/README.md[1-16]

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

---

Results up to commit b44d12d ⚖️ Balanced

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

1. Readers get the response hierarchy wrong ✓ Resolved 🐞 Bug ≡ Correctness

Description

GET /v3/service-schedules says that Vessel is at the top of the response hierarchy even though
the response root contains ServiceSchedule objects, each of which contains vesselSchedules.
Consumers using this rewritten operation description to map the payload will expect the service and
vessel levels in the opposite order from the schema.

Code

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

+        The result is `Vessel-Centric`. This means that the `Vessel` is at the top of the response hierarchy. A service is a hierarchical structure with the following elements:

Evidence

The revised operation description places vessels at the top while immediately saying services
contain vessels. The response schema is an array of ServiceSchedule, and that schema owns the
nested vesselSchedules property.

ovs/v3/OVS_v3.0.3.yaml[43-45]
ovs/v3/OVS_v3.0.3.yaml[258-261]
ovs/v3/OVS_v3.0.3.yaml[312-342]

Agent prompt

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

## Issue description
Correct the endpoint description so it reflects the actual response hierarchy: a root array of service schedules, each containing vessel schedules.

## Issue Context
The current prose calls the response vessel-centric and places `Vessel` at the top, while the OpenAPI response schema places `ServiceSchedule` objects at the root and nests `vesselSchedules` inside them.

## Fix Focus Areas
- ovs/v3/OVS_v3.0.3.yaml[43-45]
- ovs/v3/OVS_v3.0.3.yaml[258-261]
- ovs/v3/OVS_v3.0.3.yaml[312-342]

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

---

2. Users see a placeholder release date ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

README.md publishes the v3.0.3 changelog heading with the literal text RELEASE DATE instead of
an issued date. Anyone following the newly fixed v3.0.3 changelog link encounters unfinished release
metadata while every other stable v3 release is dated.

Code

ovs/v3/README.md[7]

+<a name="v303"></a>[Release v3.0.3 (RELEASE DATE)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3)

Evidence

The v3.0.3 entry contains an explicit placeholder, whereas the adjacent v3.0.2 and v3.0.1 stable
release headings contain concrete dates.

ovs/v3/README.md[7-7]
ovs/v3/README.md[19-28]

Agent prompt

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

## Issue description
Replace the literal `RELEASE DATE` placeholder in the v3.0.3 changelog heading with the actual issue date.

## Issue Context
The new changelog anchor is now the destination linked by the specification, but its heading still contains draft metadata unlike the existing stable release entries.

## Fix Focus Areas
- ovs/v3/README.md[7-7]
- ovs/v3/README.md[19-28]

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

---

[Copilot]

🟡 Changes recommended

The parameters: field for /v3/service-schedules is currently indented into the description: | block, which would break the OpenAPI structure for that operation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the OVS 3.0.3 OpenAPI specification to introduce waterway (canals/straits) support in vessel schedules by extending TransportCall.location with a WWAY location type and documenting the expected semantics for timestamps and related fields.

Changes:

• Add WaterwaySMDGLocation schema and wire it into TransportCall.location via discriminator mapping and oneOf.
• Update schedule and filter documentation to describe TransportCall as representing either ports/terminals or waterways/entry points.
• Clarify timestamp and facilityTypeCode semantics for WWAY transport calls.

File summaries

File	Description
ovs/v3/OVS_v3.0.3.yaml	Extends the OVS v3.0.3 spec with WWAY location support and updates related descriptions/filters.

Review details

Suppressed comments (2)

ovs/v3/OVS_v3.0.3.yaml:63

• Grammar issue: "specify mutually filters" is ungrammatical; it should describe that the filters are mutually exclusive.

        Be aware that it is possible to specify mutually filters, resulting in an empty response list. For example:

ovs/v3/OVS_v3.0.3.yaml:71

• Minor doc typos/grammar: "request data" should be "request date", and "endDate filters is" should be "endDate filter is".

        If no `startDate` filter is provided, **3 months** before the request data is used. If no `endDate` filters is provided, **6 months** after the request date is used.

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Lite

---

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

[HenrikHL]

/agentic_review

[qodo-code-review]

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

[Copilot]

🟡 Changes recommended

The updated documentation/spec text contains a release-date placeholder and several ambiguous phrasings that could mislead API consumers about how WWAY is represented in the schema.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

ovs/v3/OVS_v3.0.3.yaml:764

• In the eventTypeCode description, "WWAY TransportCall" is ambiguous because WWAY is a location.locationType discriminator. Clarify that the semantics apply when the containing TransportCall has location.locationType = WWAY (and likewise for the "other end" example).

            For a `WWAY` **TransportCall**, `ARRI` means arrival at the waterway location represented by that **TransportCall**, and `DEPA` means departure from the same location.

            When `waterwaySMDGEntryPointCode` is provided, both event types refer to that specific waterway point. `DEPA` does not mean that the vessel has exited the complete waterway at the point on the opposite side.

            A carrier may publish the point at the other end as another ordered `WWAY` TransportCall.

ovs/v3/OVS_v3.0.3.yaml:835

• Same ambiguity here: "WWAY TransportCall" should be phrased in terms of location.locationType to match the actual schema structure and reduce misinterpretation.

            The `BRTH` default is retained for backwards compatibility. If schema-driven tooling materializes `BRTH` for a WWAY TransportCall, consumers **MUST** disregard the value and **MUST NOT** interpret it as vessel berthing.

• Files reviewed: 2/2 changed files
• Comments generated: 3
• Review effort level: Lite

[HenrikHL]

/agentic_review

[qodo-code-review]

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

[Copilot]

🟡 Changes recommended

The spec text currently references a non-existent VesselSchedules name, which should be corrected to match the actual schema/property names before publishing.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

ovs/v3/README.md:7

• The changelog entries in this README typically include a release date in parentheses (e.g., v3.0.2, v3.0.1). v3.0.3 is missing a date, which makes it harder to correlate the spec with a release timeline.

<a name="v303"></a>[Release v3.0.3](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3)

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Lite

[HenrikHL]

/agentic_review

[qodo-code-review]

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

[Copilot]

🔵 Needs a closer look

There is at least one concrete documentation/spec issue (undefined type name in the endpoint description) that should be corrected to avoid confusing API consumers.

Review details

Suppressed comments (2)

ovs/v3/OVS_v3.0.3.yaml:43

• In this description, VesselSchedules is referenced as a schema/type name, but the schema defined in components/schemas is VesselSchedule (singular). Using an undefined type name in the API description can confuse consumers and generated docs.

        The response is an array of `ServiceSchedule` objects. Each `ServiceSchedule` can contain one or more `VesselSchedules`.

ovs/v3/README.md:7

• Release headings in this changelog typically include the release date (e.g., v3.0.2 and v3.0.1). Adding the v3.0.3 release date would keep the changelog consistent and make it easier to track when the patch was published.

<a name="v303"></a>[Release v3.0.3](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3)

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite

[HenrikHL]

/agentic_review

[qodo-code-review]

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