From 286404faff34a9467c6672e4cabb4bec53ae3e5a Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Tue, 8 Sep 2026 09:51:01 +0200 Subject: [PATCH 1/5] OVS 3.0: SD-2234: Add WaterWays to schedules --- ovs/v3/OVS_v3.0.3.yaml | 170 ++++++++++++++++++++++++++++++++++------- 1 file changed, 143 insertions(+), 27 deletions(-) diff --git a/ovs/v3/OVS_v3.0.3.yaml b/ovs/v3/OVS_v3.0.3.yaml index 8070535e..e7638d0a 100644 --- a/ovs/v3/OVS_v3.0.3.yaml +++ b/ovs/v3/OVS_v3.0.3.yaml @@ -15,7 +15,7 @@ info: This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer Portal](https://developer.dcsa.org/api_design) ### Changelog and Contact Us - For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ovs/v3#v302). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + 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). API specification issued by [DCSA.org](https://dcsa.org/). contact: @@ -38,25 +38,38 @@ paths: Get a list of Schedules operationId: get-v3-service-schedules description: | - Get a list of service schedules. The result is `Vessel-Centric` - this means that the `Vessel` is in the top of the hierarchy of the response structure. A service is a heirarchical structure with the following elements: - - One or more `Services` which can contain one or more `Vessels` - - A `Vessel` which can call multiple `Ports` (`TransportCalls`). - - A `Port` (`TransportCall`) can contain one or more `TimeStamps`. + Get a list of service schedules. - 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`. + The result is `Vessel-Centric`. This means that the `Vessel` is at the top of the response hierarchy. A service is a heirarchical structure with the following elements: + - One or more `Services`, which can contain one or more `Vessels`. + - A `Vessel`, which can call multiple `TransportCalls`. + - A `TransportCall`, which represents a location in the vessel schedule. It can represent a port, optionally further specified by a terminal, or a waterway, optionally further specified by a waterway entry point. + - A `TransportCall` can contain one or more `Timestamps`. + + 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 by the `responseScope` query parameter. This means that even though a filter only matches a single `TransportCall` in a voyage, or a single `Timestamp` within a `TransportCall`, **the entire matched voyage** is returned. + + If the `carrierImportVoyageNumber` of the matched `TransportCall` differs from its `carrierExportVoyageNumber`, the **entire Voyage** for both voyage numbers is included. + + For example, when `&UNLocationCode=DEHAM` is used as a filter parameter, entire voyages containing a `TransportCall` with `UNLocationCode=DEHAM` are returned. - **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. + **Note as of v3.0.2:** If `responseScope` is set to `MATCHED_CALLS`, only **partial voyage(s) may be returned**. If a filter only matches a single `TransportCall` in a voyage, or a single `Timestamp` within a `TransportCall`, **only the matching `TransportCalls`** are returned. - Be aware that it is possible to specify filters that are mutially exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time: + If the `carrierImportVoyageNumber` of a `TransportCall` differs from its `carrierExportVoyageNumber`, the `TransportCall` is included when either or both voyage numbers match the filter. + + For example, when `&UNLocationCode=DEHAM` is used, only `TransportCalls` with `UNLocationCode=DEHAM` are included. + + Be aware that it is possible to specify mutually filters, resulting in an empty response list. For example: ``` &vesselIMONumber=9321483&vesselName=King of the Seas ``` - If no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list + If no `Vessel` exists where `vesselIMONumber` is `9321483` and `vesselName` is `King of the Seas`, the result is an empty list. - If no `startDate` filter is provided then **3 months** prior to the request data is used. If no `endDate` filters is provided then **6 months** after the request date is used. - parameters: + 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. + parameters: - name: carrierServiceName in: query description: | @@ -112,7 +125,9 @@ paths: - name: carrierVoyageNumber in: query description: | - The carrier specific identifier of a `Voyage` - can be both **importVoyageNumber** and **exportVoyageNumber**. The result will only return schedules including the `Ports` where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber` + The carrier-specific identifier of a `Voyage`. It can be either the `carrierImportVoyageNumber` or the `carrierExportVoyageNumber`. + + The result will only return schedules containing `TransportCalls` where `carrierVoyageNumber` matches either `carrierImportVoyageNumber` or `carrierExportVoyageNumber`. schema: type: string maxLength: 50 @@ -120,7 +135,9 @@ paths: - name: universalVoyageReference in: query description: | - The Universal Reference of a `Voyage` - can be both **importUniversalVoyageReference** and **exportUniversalVoyageReference**. The result will only return schedules including the `Ports` where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference` + The universal reference of a `Voyage`. It can be either the `universalImportVoyageReference` or the `universalExportVoyageReference`. + + The result will only return schedules containing `TransportCalls` where `universalVoyageReference` matches either `universalImportVoyageReference` or `universalExportVoyageReference`. schema: type: string pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ @@ -129,7 +146,9 @@ paths: - name: UNLocationCode in: query description: | - The `UN Location Code` specifying where a port is located. Specifying this filter will only return schedules including **entire Voyages** related to this particular `UN Location Code`. + The `UN Location Code` identifying a location associated with a `TransportCall`. The location can, for example, represent a port or a waterway. + + Specifying this filter returns schedules containing entire voyages associated with the given `UNLocationCode`, subject to the selected `responseScope`. schema: type: string pattern: ^[A-Z]{2}[A-Z2-9]{3}$ @@ -155,7 +174,13 @@ paths: - name: startDate in: query description: | - The start date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or after (`≥`) the `startDate` the **entire Voyage** (import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **3 months** prior to request time. + The start date of the period for which schedule information is requested. + + If the date of any Timestamp (`ATA`, `ETA`, or `PTA`) inside a `TransportCall` is on or after (`>=`) the `startDate`, the entire voyage associated with that `TransportCall` is included, subject to the selected `responseScope`. + + Date matching is performed using the local date at the location represented by the `TransportCall`. + + If this filter is not provided, the default is **three months** before the request date. schema: type: string format: date @@ -163,7 +188,13 @@ paths: - name: endDate in: query description: | - The end date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or before (`≤`) the `endDate` the **entire Voyage**(import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **6 months** after request time. + The end date of the period for which schedule information is requested. + + If the date of any Timestamp (`ATA`, `ETA`, or `PTA`) inside a `TransportCall` is on or before (`<=`) the `endDate`, the entire voyage associated with that `TransportCall` is included, subject to the selected `responseScope`. + + Date matching is performed using the local date at the location represented by the `TransportCall`. + + If this filter is not provided, the default is **six months** after the request date. schema: type: string format: date @@ -282,7 +313,9 @@ components: type: object title: Service Schedule description: | - The timetable of the roundtrip sequence of ports being served by a (number of) vessel(s) on a specific Proforma (schedule). Synonyms are rotation, loop, or string. A Service is defined by rotation, transit times, weekdays of departure per port, and frequencies. + The timetable for the roundtrip sequence of `TransportCalls` made by one or more vessels on a specific proforma schedule. + + A service is defined by its rotation, transit times, departure weekdays at the relevant locations, and frequency. Synonyms include rotation, loop, and string. properties: carrierServiceName: type: string @@ -314,7 +347,7 @@ components: type: object title: Vessel Schedule description: | - The timetable of departure and arrival times for each port call on the rotation of the vessel in question. + The timetable of arrival and departure times for each `TransportCall` in the rotation of the vessel. properties: vesselOperatorSMDGLinerCode: type: string @@ -389,21 +422,31 @@ components: type: object title: Transport Call description: | - A transportCall in the schedule. A transportCall can be either just a Port or further specified as a terminalCall. - - The order of the list is the sequence of the list + A **TransportCall** represents a location in the vessel schedule. + + It can represent a port, which may be further specified by a terminal, or a waterway, which may be further specified by an SMDG waterway entry point. + + One `WWAY` **TransportCall** represents one waterway location. When `waterwaySMDGEntryPointCode` is provided, it represents the specific waterway point identified by the combination of `UNLocationCode` and `waterwaySMDGEntryPointCode`. + + The order of the **TransportCalls** in the list defines their sequence in the vessel schedule. properties: portVisitReference: type: string maxLength: 50 description: | - The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call + The unique reference used to associate different `transportCallReferences` with the same port visit. The reference is provided by the port to identify the port call. + + This property applies only when the `TransportCall` represents a port. It is not applicable to a `TransportCall` where `location.locationType` is `WWAY` and **SHOULD** be omitted in that case. example: NLAMS1234589 transportCallReference: type: string maxLength: 100 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. + The unique reference for a **TransportCall**. It's the vessel operator's responsibility to provide the `transportCallReference`, 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. + + For a **TransportCall** where `location.locationType` is `WWAY`, the reference identifies the scheduled call at the waterway location represented by that **TransportCall**. When `waterwaySMDGEntryPointCode` is provided, it includes that specific waterway point. + + It does not identify the complete passage through the waterway. example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 carrierImportVoyageNumber: type: string @@ -439,17 +482,21 @@ components: example: 2103N location: description: | - General purpose object to capture location-related data, the location can be specified in **one** of the following ways: `UN Location Code`, a `Facility` or an `Address`. + General purpose object to capture location-related data. A location can be specified as a `UN Location Code`, an `SMDG Facility`, an `Address` or an `SMDG waterway` location. + + Consumers implemented against OVS versions that do not support the `WWAY` location type may need to be updated before processing this location type. discriminator: propertyName: locationType mapping: UNLO: "#/components/schemas/UNLocationLocation" FACS: "#/components/schemas/FacilitySMDGLocation" ADDR: "#/components/schemas/AddressLocation" + WWAY: "#/components/schemas/WaterwaySMDGLocation" oneOf: - $ref: '#/components/schemas/UNLocationLocation' - $ref: '#/components/schemas/FacilitySMDGLocation' - $ref: '#/components/schemas/AddressLocation' + - $ref: '#/components/schemas/WaterwaySMDGLocation' statusCode: type: string description: | @@ -512,6 +559,7 @@ components: example: Port of Amsterdam locationType: type: string + pattern: ^UNLO$ maxLength: 4 description: | Discriminator used to identify this as a `UNLocation` location interface. @@ -546,6 +594,7 @@ components: example: Port of Amsterdam locationType: type: string + pattern: ^FACS$ maxLength: 4 description: | Discriminator used to identify this as a `Facility Location` interface only using `SMDG` code list. @@ -589,6 +638,7 @@ components: example: Port of Amsterdam locationType: type: string + pattern: ^ADDR$ maxLength: 4 description: | Discriminator used to identify this as an `Address` location interface. @@ -642,11 +692,61 @@ components: required: - address - locationType + + WaterwaySMDGLocation: + type: object + title: Waterway SMDG Location + 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. + + If `waterwaySMDGEntryPointCode` is omitted, the location identifies only the waterway. No specific waterway point can then be inferred from an `ARRI` or `DEPA` timestamp. + properties: + locationName: + type: string + maxLength: 100 + description: The name of the waterway or waterway point. + example: Panama Canal + locationType: + type: string + pattern: ^WWAY$ + maxLength: 4 + description: | + Discriminator identifying this as an **SMDG waterway location**. + example: WWAY + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://en.wikipedia.org/wiki/UN/LOCODE) + example: PAPCN + waterwaySMDGEntryPointCode: + type: string + maxLength: 10 + description: | + The **SMDG Waterway Code List** entry-point code. The code is not unique by itself and must be interpreted together with `UNLocationCode`. + + This property is optional. When omitted, the location identifies the waterway but not a specific point. + + Valid values are published in the [SMDG Waterway Code List](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). + example: ATL + required: + - locationType + - UNLocationCode + Timestamp: type: object title: Timestamp description: | - A timestamp for a port. + A timestamp for the location represented by the containing **TransportCall**. properties: eventTypeCode: type: string @@ -654,6 +754,12 @@ components: Identifier for type of `transportEvent` - `ARRI` (Arrived) - `DEPA` (Departed) + + 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. enum: - ARRI - DEPA @@ -714,11 +820,21 @@ components: maxLength: 4 default: BRTH description: | - The code to identify the specific type of facility. The following values are supported: + The code identifying the type of facility associated with the timestamp. + + Supported values: - `PBPL` (Pilot Boarding Place) - `BRTH` (Berth) - If no value is provided, `BRTH` is the default value. + For TransportCalls representing ports or facilities, `BRTH` is the default when this property is omitted. + + 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 + - an API consumer **SHOULD** ignore `facilityTypeCode` if it is nevertheless present. + + Waterway locations represent locations without vessel berthing. example: BRTH required: - eventClassifierCode From b44d12dae11e404ba4ef6bd6212213558d597ae1 Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Tue, 8 Sep 2026 10:52:29 +0200 Subject: [PATCH 2/5] Fix review comments --- ovs/v3/OVS_v3.0.3.yaml | 30 ++++++++++++++---------------- ovs/v3/README.md | 12 ++++++++++++ 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/ovs/v3/OVS_v3.0.3.yaml b/ovs/v3/OVS_v3.0.3.yaml index e7638d0a..1427cc1a 100644 --- a/ovs/v3/OVS_v3.0.3.yaml +++ b/ovs/v3/OVS_v3.0.3.yaml @@ -40,7 +40,7 @@ paths: description: | Get a list of service schedules. - The result is `Vessel-Centric`. This means that the `Vessel` is at the top of the response hierarchy. A service is a heirarchical structure with the following elements: + 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: - One or more `Services`, which can contain one or more `Vessels`. - A `Vessel`, which can call multiple `TransportCalls`. - A `TransportCall`, which represents a location in the vessel schedule. It can represent a port, optionally further specified by a terminal, or a waterway, optionally further specified by a waterway entry point. @@ -60,7 +60,7 @@ paths: For example, when `&UNLocationCode=DEHAM` is used, only `TransportCalls` with `UNLocationCode=DEHAM` are included. - Be aware that it is possible to specify mutually filters, resulting in an empty response list. For example: + Be aware that it is possible to specify mutually exclusive filters, resulting in an empty response list. For example: ``` &vesselIMONumber=9321483&vesselName=King of the Seas @@ -68,8 +68,8 @@ paths: If no `Vessel` exists where `vesselIMONumber` is `9321483` and `vesselName` is `King of the Seas`, the result is an empty list. - 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. - parameters: + If no `startDate` filter is provided, **3 months** before the request date is used. If no `endDate` filter is provided, **6 months** after the request date is used. + parameters: - name: carrierServiceName in: query description: | @@ -721,22 +721,24 @@ components: minLength: 5 maxLength: 5 description: | - The UN Location code specifying where the place is located. The pattern used must be + The UN/LOCODE identifying the waterway. The pattern used must be: - 2 characters for the country code using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used - More info can be found here: [UN/LOCODE](https://en.wikipedia.org/wiki/UN/LOCODE) + More information is available from [UN/LOCODE](https://en.wikipedia.org/wiki/UN/LOCODE). example: PAPCN waterwaySMDGEntryPointCode: type: string - maxLength: 10 + maxLength: 6 description: | - The **SMDG Waterway Code List** entry-point code. The code is not unique by itself and must be interpreted together with `UNLocationCode`. + A waterway location identified using the [**SMDG Waterway Code List**](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). + + Waterway locations represent locations without loading or discharge operations and without vessel berthing. - This property is optional. When omitted, the location identifies the waterway but not a specific point. + `UNLocationCode` identifies the waterway. When `waterwaySMDGEntryPointCode` is provided, the combination of the two values identifies a specific point on the waterway. - Valid values are published in the [SMDG Waterway Code List](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). + If `waterwaySMDGEntryPointCode` is omitted, the location identifies only the waterway. No specific waterway point can then be inferred from an `ARRI` or `DEPA` timestamp. example: ATL required: - locationType @@ -828,13 +830,9 @@ components: For TransportCalls representing ports or facilities, `BRTH` is the default when this property is omitted. - 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 - - an API consumer **SHOULD** ignore `facilityTypeCode` if it is nevertheless present. + `facilityTypeCode` has no business meaning when the containing **TransportCall** has `location.locationType` equal to `WWAY`. Providers **SHOULD** omit it for `WWAY` **TransportCalls**. - Waterway locations represent locations without vessel berthing. + 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. example: BRTH required: - eventClassifierCode diff --git a/ovs/v3/README.md b/ovs/v3/README.md index 40017b27..ab1c95fe 100644 --- a/ovs/v3/README.md +++ b/ovs/v3/README.md @@ -4,6 +4,18 @@ The DCSA OVS API is documented on [**SwaggerHub**](https://app.swaggerhub.com/ap The primary purpose of this API is to specify endPoints for schedules shared between Vessel Partners. +[Release v3.0.3 (RELEASE DATE)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3) +--- +A patch adding support for waterway locations in operational vessel schedules. + +- Added `WWAY` as a location discriminator value. +- Added `WaterwaySMDGLocation`. +- Added optional `waterwaySMDGEntryPointCode`. +- Clarified `ARRI` and `DEPA` semantics for waterway locations. +- Clarified that waterway locations do not represent loading, discharge, or berthing operations. +- Constrained each location schema's `locationType` using an exact pattern to resolve overlapping `oneOf` validation. +- Generalized port-only wording to cover all TransportCalls. + [Release v3.0.2 (12 June 2026)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.2) --- An update to allow partial schedules and add `facilityTypeCode`. From b249f705bd88f0e184ffe9cbf48ff0d9398fd9a0 Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Tue, 8 Sep 2026 11:18:34 +0200 Subject: [PATCH 3/5] Fix review comments --- ovs/v3/OVS_v3.0.3.yaml | 30 +++++++++++++++++------------- ovs/v3/README.md | 2 +- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/ovs/v3/OVS_v3.0.3.yaml b/ovs/v3/OVS_v3.0.3.yaml index 1427cc1a..325b3324 100644 --- a/ovs/v3/OVS_v3.0.3.yaml +++ b/ovs/v3/OVS_v3.0.3.yaml @@ -40,10 +40,12 @@ paths: description: | Get a list of service schedules. - 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: - - One or more `Services`, which can contain one or more `Vessels`. - - A `Vessel`, which can call multiple `TransportCalls`. - - A `TransportCall`, which represents a location in the vessel schedule. It can represent a port, optionally further specified by a terminal, or a waterway, optionally further specified by a waterway entry point. + The response is an array of `ServiceSchedule` objects. Each `ServiceSchedule` can contain one or more `VesselSchedules`. + + The response hierarchy is: + - One or more `ServiceSchedule`, which can contain one or more `VesselSchedules`. + - A `VesselSchedule`, which can contain multiple `TransportCalls`. + - A `TransportCall` represents a location in the vessel schedule. It can represent a port, optionally further specified by a terminal, or a waterway, optionally further specified by an SMDG waterway entry point. - A `TransportCall` can contain one or more `Timestamps`. The number of service schedules in the list can be narrowed down by providing filter parameters. @@ -426,7 +428,7 @@ components: It can represent a port, which may be further specified by a terminal, or a waterway, which may be further specified by an SMDG waterway entry point. - One `WWAY` **TransportCall** represents one waterway location. When `waterwaySMDGEntryPointCode` is provided, it represents the specific waterway point identified by the combination of `UNLocationCode` and `waterwaySMDGEntryPointCode`. + One **TransportCall** with `location.locationType` set to `WWAY` represents one waterway location. When `waterwaySMDGEntryPointCode` is provided, it represents the specific waterway point identified by the combination of `UNLocationCode` and `waterwaySMDGEntryPointCode`. The order of the **TransportCalls** in the list defines their sequence in the vessel schedule. properties: @@ -702,6 +704,8 @@ components: `UNLocationCode` identifies the waterway. When `waterwaySMDGEntryPointCode` is provided, the combination of the two values identifies a specific point on the waterway. If `waterwaySMDGEntryPointCode` is omitted, the location identifies only the waterway. No specific waterway point can then be inferred from an `ARRI` or `DEPA` timestamp. + + Waterway locations represent locations without loading or discharge operations and without vessel berthing. properties: locationName: type: string @@ -732,13 +736,13 @@ components: type: string maxLength: 6 description: | - A waterway location identified using the [**SMDG Waterway Code List**](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). + The SMDG entry-point code identifying a specific point on the waterway. - Waterway locations represent locations without loading or discharge operations and without vessel berthing. + The code is not unique by itself and must be interpreted together with `UNLocationCode`. - `UNLocationCode` identifies the waterway. When `waterwaySMDGEntryPointCode` is provided, the combination of the two values identifies a specific point on the waterway. + This property is optional. When omitted, the location identifies the waterway but not a specific waterway point. - If `waterwaySMDGEntryPointCode` is omitted, the location identifies only the waterway. No specific waterway point can then be inferred from an `ARRI` or `DEPA` timestamp. + Valid values are published in the [SMDG Waterway Code List](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). example: ATL required: - locationType @@ -757,11 +761,11 @@ components: - `ARRI` (Arrived) - `DEPA` (Departed) - For a `WWAY` **TransportCall**, `ARRI` means arrival at the waterway location represented by that **TransportCall**, and `DEPA` means departure from the same location. + For a **TransportCall** with `location.locationType` set to `WWAY`, `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. + A carrier may publish the point at the other end as another ordered **TransportCall** with `location.locationType` set to `WWAY`. enum: - ARRI - DEPA @@ -830,9 +834,9 @@ components: For TransportCalls representing ports or facilities, `BRTH` is the default when this property is omitted. - `facilityTypeCode` has no business meaning when the containing **TransportCall** has `location.locationType` equal to `WWAY`. Providers **SHOULD** omit it for `WWAY` **TransportCalls**. + `facilityTypeCode` has no business meaning when the containing **TransportCall** has `location.locationType` set to `WWAY`. Providers **SHOULD** omit it for such TransportCalls. - 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. + The `BRTH` default is retained for backwards compatibility. If schema-driven tooling materializes `BRTH` for a **TransportCall** with `location.locationType` set to `WWAY`, consumers **MUST** disregard the value and **MUST NOT** interpret it as vessel berthing. example: BRTH required: - eventClassifierCode diff --git a/ovs/v3/README.md b/ovs/v3/README.md index ab1c95fe..92de668d 100644 --- a/ovs/v3/README.md +++ b/ovs/v3/README.md @@ -4,7 +4,7 @@ The DCSA OVS API is documented on [**SwaggerHub**](https://app.swaggerhub.com/ap The primary purpose of this API is to specify endPoints for schedules shared between Vessel Partners. -[Release v3.0.3 (RELEASE DATE)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3) +[Release v3.0.3](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3) --- A patch adding support for waterway locations in operational vessel schedules. From a37643555b4e73c0218e39d20737275a3e6f9c7c Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Tue, 8 Sep 2026 11:33:38 +0200 Subject: [PATCH 4/5] Fix review comment --- ovs/v3/OVS_v3.0.3.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ovs/v3/OVS_v3.0.3.yaml b/ovs/v3/OVS_v3.0.3.yaml index 325b3324..d61f00b1 100644 --- a/ovs/v3/OVS_v3.0.3.yaml +++ b/ovs/v3/OVS_v3.0.3.yaml @@ -43,7 +43,7 @@ paths: The response is an array of `ServiceSchedule` objects. Each `ServiceSchedule` can contain one or more `VesselSchedules`. The response hierarchy is: - - One or more `ServiceSchedule`, which can contain one or more `VesselSchedules`. + - One or more `ServiceSchedule`, which can contain one or more `VesselSchedule`. - A `VesselSchedule`, which can contain multiple `TransportCalls`. - A `TransportCall` represents a location in the vessel schedule. It can represent a port, optionally further specified by a terminal, or a waterway, optionally further specified by an SMDG waterway entry point. - A `TransportCall` can contain one or more `Timestamps`. From de4a6b5bc099d8e4b0ada35d35740bbd6ad74407 Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Tue, 8 Sep 2026 11:52:53 +0200 Subject: [PATCH 5/5] Fix review comments --- ovs/v3/OVS_v3.0.3.yaml | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/ovs/v3/OVS_v3.0.3.yaml b/ovs/v3/OVS_v3.0.3.yaml index d61f00b1..e2fcfe45 100644 --- a/ovs/v3/OVS_v3.0.3.yaml +++ b/ovs/v3/OVS_v3.0.3.yaml @@ -40,14 +40,14 @@ paths: description: | Get a list of service schedules. - The response is an array of `ServiceSchedule` objects. Each `ServiceSchedule` can contain one or more `VesselSchedules`. + The response is an array of `ServiceSchedule` objects. Each `ServiceSchedule` can contain one or more `VesselSchedule` objects in its `vesselSchedules` property. The response hierarchy is: - - One or more `ServiceSchedule`, which can contain one or more `VesselSchedule`. - - A `VesselSchedule`, which can contain multiple `TransportCalls`. + - A `ServiceSchedule` can contain one or more `VesselSchedule` objects in `vesselSchedules`. + - A `VesselSchedule` can contain multiple `TransportCall` objects in `transportCalls`. - A `TransportCall` represents a location in the vessel schedule. It can represent a port, optionally further specified by a terminal, or a waterway, optionally further specified by an SMDG waterway entry point. - - A `TransportCall` can contain one or more `Timestamps`. - + - A `TransportCall` can contain one or more `Timestamp` objects in `timestamps`. + 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 by the `responseScope` query parameter. This means that even though a filter only matches a single `TransportCall` in a voyage, or a single `Timestamp` within a `TransportCall`, **the entire matched voyage** is returned. @@ -740,9 +740,7 @@ components: The code is not unique by itself and must be interpreted together with `UNLocationCode`. - 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/). + This property is optional. When omitted, the location identifies the waterway but not a specific waterway point. When provided, it **MUST** contain a valid code published in the [SMDG Waterway Code List](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). example: ATL required: - locationType