Prepare for next patch releases

[HenrikHL]

PR Type

Documentation

---

Description

• Added OpenAPI 3.0.3 specifications for multiple DCSA API versions preparing for next patch releases

• Commercial Schedules API v1.0.2: Complete specification with three main endpoints (/v1/point-to-point-routes, /v1/port-schedules, /v1/vessel-schedules) and comprehensive schema definitions for routing and scheduling data

• Operational Vessel Schedules API v3.0.2: New specification with /v3/service-schedules GET endpoint, advanced filtering parameters, and support for multiple location types using discriminator pattern

• eBL Endorsement Chain API v3.0.3: New specification for retrieving endorsement chains with detailed schema definitions and examples for various endorsement scenarios

• eBL Surrender API v3.0.3: New specification with POST endpoints for surrender requests and responses, including surrender request codes and reason codes

• All specifications include comprehensive error handling with detailed error response schemas and appropriate HTTP status codes

---

Diagram Walkthrough

flowchart LR
  A["API Specifications"] --> B["Commercial Schedules v1.0.2"]
  A --> C["Operational Vessel Schedules v3.0.2"]
  A --> D["eBL v3.0.3"]
  D --> E["Endorsement Chain API"]
  D --> F["Surrender API"]
  B --> G["3 Main Endpoints"]
  C --> H["Service Schedules Endpoint"]
  E --> I["GET Endorsement Chains"]
  F --> J["POST Surrender Requests/Responses"]

Loading

File Walkthrough

Relevant files

Documentation

CS_v1.0.2.yaml Commercial Schedules API v1.0.2 OpenAPI specification        cs/v1/CS_v1.0.2.yaml Added complete OpenAPI 3.0.3 specification for Commercial Schedules API v1.0.2 Defined three main endpoints: /v1/point-to-point-routes, /v1/port-schedules, and /v1/vessel-schedules Implemented comprehensive schema definitions for routing, scheduling, and location data structures Included error handling with detailed error response schemas and HTTP status codes (200, 400, 500) +1773/-0 OVS_v3.0.2.yaml Operational Vessel Schedules API v3.0.2 OpenAPI specification ovs/v3/OVS_v3.0.2.yaml Added complete OpenAPI 3.0.3 specification for Operational Vessel Schedules API v3.0.2 Implemented /v3/service-schedules GET endpoint with comprehensive filtering parameters Defined schema structures for ServiceSchedule, VesselSchedule, TransportCall, and location types Added support for multiple location types using discriminator pattern (UNLocationLocation, FacilitySMDGLocation, AddressLocation) +820/-0  EBL_END_v3.0.3.yaml DCSA eBL Endorsement Chain API v3.0.3 specification            ebl/v3/endorsement/EBL_END_v3.0.3.yaml New OpenAPI 3.0.3 specification file for DCSA eBL Endorsement Chain API Defines GET endpoint to retrieve endorsement chains by transportDocumentReference with optional filtering by carrierSCACCode and transportDocumentSubReference Includes comprehensive schema definitions for EndorsementChain, EndorsementChainLink, party types (ActorParty, RecipientParty), and error responses Provides detailed examples of endorsement chains for surrendered straight B/L, B/L with on-behalf-of parties, and multiple document versions +890/-0  EBL_SUR_v3.0.3.yaml DCSA eBL Surrender API v3.0.3 specification                            ebl/v3/surrender/EBL_SUR_v3.0.3.yaml New OpenAPI 3.0.3 specification file for DCSA eBL Surrender API Defines POST endpoints for surrender requests (/v3/ebl-surrender-requests) and surrender responses (/v3/ebl-surrender-responses) Includes schema definitions for SurrenderRequestDetails, SurrenderRequestAnswer, party types, and error handling Specifies surrender request codes (SREQ for delivery, AREQ for amendment) and reason codes (SWTP, COD, SWI) +706/-0

---

[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
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	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: 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
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No audit logs: The OpenAPI spec defines read endpoints and error schemas but does not include any requirements or fields for auditing user actions, so it is unclear whether critical actions will be logged by the implementation. Referred Code paths: /v1/point-to-point-routes: get: summary: Point to Point Routing tags: - Point To Point responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/PointToPoint' headers: API-Version: schema: type: string example: 1.0.1 description: | ... (clipped 1714 lines) 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: Logging unspecified: The specification defines error response structures but does not state logging behavior or redaction, so it is not possible to verify that sensitive data will be excluded from logs. Referred Code title: Error Response type: object required: - httpMethod - requestUri - statusCode - statusCodeText - errorDateTime - errors properties: httpMethod: type: string example: POST enum: - GET - HEAD - POST - PUT - DELETE - OPTION - PATCH ... (clipped 37 lines) Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

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

[Copilot]

Pull request overview

This PR adds OpenAPI 3.0.3 specifications for upcoming patch releases across multiple DCSA APIs, preparing for version updates to Commercial Schedules (v1.0.2), Operational Vessel Schedules (v3.0.2), and eBL APIs (v3.0.3).

Key Changes:

• Introduction of Commercial Schedules API v1.0.2 with three main endpoints for point-to-point routing, port schedules, and vessel schedules
• Addition of Operational Vessel Schedules API v3.0.2 with enhanced filtering and location type support
• New eBL v3.0.3 specifications for both Endorsement Chain and Surrender APIs

Reviewed changes

Copilot reviewed 4 out of 7 changed files in this pull request and generated 3 comments.

File	Description
cs/v1/CS_v1.0.2.yaml	Complete Commercial Schedules API specification with routing, port schedule, and vessel schedule endpoints
ovs/v3/OVS_v3.0.2.yaml	Operational Vessel Schedules API with service schedules endpoint and discriminator-based location types
ebl/v3/endorsement/EBL_END_v3.0.3.yaml	eBL Endorsement Chain API for retrieving endorsement history with comprehensive examples
ebl/v3/surrender/EBL_SUR_v3.0.3.yaml	eBL Surrender API for handling surrender requests and responses with detailed party schemas

---

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

[Copilot]

Corrected spelling of 'erorCodeMessage' to 'errorCodeMessage'.

Suggested change

	erorCodeMessage: UNLocationCode does not exist
	errorCodeMessage: UNLocationCode does not exist

[Copilot]

Corrected spelling of 'erorCodeMessage' to 'errorCodeMessage'.

Suggested change

	erorCodeMessage:
	errorCodeMessage:

[Copilot]

Corrected spelling of 'OPTIONS' to 'OPTION' to match the enum pattern used in other error response schemas in this PR.

Suggested change

	- OPTIONS
	- OPTION

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Structure OpenAPI specs for maintainability To improve maintainability and reuse, the large, monolithic OpenAPI specification files should be split into smaller, more manageable parts using $ref to link them together. Examples: ebl/v3/EBL_v3.0.3.yaml [1-9005] openapi: 3.0.3 info: version: 3.0.3 title: DCSA Shipping Instructions and Transport Document API description: | <h1>DCSA OpenAPI specification for the Shipping Instructions and Transport Document process</h1> This API is intended as an API between a carrier and anyone creating a `Shipping Instructions` and approving a `Transport Document`. The process includes: - Shipping Instructions submission ... (clipped 8995 lines) bkg/v2/BKG_v2.0.4.yaml [1-6966] openapi: 3.0.3 info: version: 2.0.4 title: DCSA Booking API description: | <h1>DCSA OpenAPI specification for the Booking process</h1> This API is intended as an API between a carrier and anyone creating a `Booking`. The process includes: - Booking request ... (clipped 6956 lines) Solution Walkthrough: Before: # ebl/v3/EBL_v3.0.3.yaml (single massive file) openapi: 3.0.3 info: ... paths: '/v3/shipping-instructions': post: summary: Creates a Shipping Instructions ... requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateShippingInstructions' ... components: schemas: CreateShippingInstructions: type: object ... ErrorResponse: type: object ... # ... thousands of lines of schemas ... After: # ebl/v3/EBL_v3.0.3.yaml (main file) openapi: 3.0.3 info: ... paths: '/v3/shipping-instructions': $ref: './paths/shipping-instructions.yaml' '/v3/transport-documents/{transportDocumentReference}': $ref: './paths/transport-documents.yaml' ... components: schemas: $ref: './schemas/index.yaml' parameters: $ref: './parameters/index.yaml' examples: $ref: './examples/index.yaml' # ebl/v3/schemas/index.yaml CreateShippingInstructions: $ref: './CreateShippingInstructions.yaml' ErrorResponse: $ref: './ErrorResponse.yaml' ... Suggestion importance[1-10]: 8 __ Why: The suggestion addresses a critical maintainability and architectural issue with the newly added OpenAPI specifications, which are over 9000 lines long, making this a significant quality improvement.	Medium
Possible issue	Make error code a required field Make the errorCode field mandatory in the DetailedError schema to enable reliable, programmatic error handling by API clients. ebl/v3/issuance/EBL_ISS_v3.0.3.yaml [244-296] DetailedError: type: object title: Detailed Error description: | A detailed description of what has caused the error. properties: errorCode: type: integer format: int32 description: | The detailed error code returned. - `7000-7999` Technical error codes - `8000-8999` Functional error codes - `9000-9999` API provider-specific error codes [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). minimum: 7000 maximum: 9999 example: 7003 property: type: string maxLength: 100 description: | The name of the property causing the error. example: facilityCode value: type: string maxLength: 500 description: | The value of the property causing the error serialised as a string exactly as in the original request. example: SG SIN WHS jsonPath: type: string maxLength: 500 description: | A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). example: $.location.facilityCode errorCodeText: description: | A standard short description corresponding to the `errorCode`. type: string maxLength: 100 example: invalidData errorCodeMessage: type: string maxLength: 5000 description: | A long description corresponding to the `errorCode` with additional information. example: Spaces not allowed in facility code required: + - errorCode - errorCodeText - errorCodeMessage Apply / Chat Suggestion importance[1-10]: 8 __ Why: The suggestion correctly points out that the errorCode should be required for programmatic error handling, which is crucial for API clients. Making it mandatory improves the robustness of the error response schema.	Medium
	Enforce mutual exclusivity of date fields Enforce the mutual exclusivity of shippedOnBoardDate and receivedForShipmentDate in the TransportDocument schema using a oneOf constraint to match the documented requirement. ebl/v3/issuance/EBL_ISS_v3.0.3.yaml [549-956] TransportDocument: type: object title: Transport Document description: | The document that governs the terms of carriage between shipper and carrier for maritime transportation. Two distinct types of transport documents exist: - Bill of Lading - Sea Waybill. properties: transportDocumentReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 20 description: | A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. example: HHL71800000 ... - shippedOnBoardDate: - type: string - format: date - description: | - Date when the last container that is linked to the transport document is physically loaded onboard the vessel indicated on the transport document. + oneOf: + - required: [shippedOnBoardDate] + - required: [receivedForShipmentDate] + allOf: + - properties: + shippedOnBoardDate: + type: string + format: date + description: | + Date when the last container that is linked to the transport document is physically loaded onboard the vessel indicated on the transport document. - When provided on a transport document, the transportDocument is a `Shipped On Board` B/L. + When provided on a transport document, the transportDocument is a `Shipped On Board` B/L. - Exactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L. - example: '2020-12-12' - ... - receivedForShipmentDate: - type: string - format: date - description: | - Date when the last container linked to the transport document is physically in the terminal (customers cleared against the intended vessel). + Exactly one of `shippedOnBoardDate` and `receiveForShipmentDate` must be provided on an issued B/L. + example: '2020-12-12' + receivedForShipmentDate: + type: string + format: date + description: | + Date when the last container linked to the transport document is physically in the terminal (customers cleared against the intended vessel). - When provided on a transport document, the transportDocument is a `Received For Shipment` B/L. + When provided on a transport document, the transportDocument is a `Received For Shipment` B/L. - Exactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L. - example: '2020-12-12' + Exactly one of `shippedOnBoardDate` and `receiveForShipmentDate` must be provided on an issued B/L. + example: '2020-12-12' ... [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that a documented constraint (oneOf shippedOnBoardDate or receivedForShipmentDate) is not enforced in the schema and proposes a valid fix, improving data integrity.	Medium
	Simplify and correct schema validation Refactor the PartyContactDetail schema to more clearly and correctly enforce that at least one of phone or email is provided, improving readability and adherence to OpenAPI best practices. ebl/v3/issuance/EBL_ISS_v3.0.3.yaml [960-1006] PartyContactDetail: type: object title: Party Contact Detail description: | The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided. example: name: Henrik phone: +45 51801234 properties: name: type: string pattern: ^\S(?:.*\S)?$ maxLength: 35 description: | Name of the contact example: Henrik + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + email: + type: string + pattern: ^.+@\S+$ + maxLength: 100 + description: | + `E-mail` address to be used + example: info@dcsa.org anyOf: - - type: object - title: Phone required - description: | - `Phone` is mandatory to provide - properties: - phone: - type: string - pattern: ^\S(?:.*\S)?$ - maxLength: 30 - description: | - Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). - example: +45 70262970 - required: - - phone - - type: object - title: Email required - description: | - `Email` is mandatory to provide - properties: - email: - type: string - pattern: ^.+@\S+$ - maxLength: 100 - description: | - `E-mail` address to be used - example: info@dcsa.org - required: - - email + - required: [phone] + - required: [email] required: - name Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies a confusing and non-standard way of defining conditional properties and proposes a much cleaner, more idiomatic, and maintainable solution using anyOf with required.	Low
	Correct httpMethod in error examples In the 404 Not Found error examples for the PATCH /v2/bookings/{bookingReference} operation, change the httpMethod from GET to PATCH to match the operation. bkg/v2/BKG_v2.0.4.yaml [1656-1696] examples: notFoundExample: summary: | Not Found request description: | The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system. **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" value: - httpMethod: GET + httpMethod: PATCH requestUri: /v2/bookings/cbrr-123 statusCode: 404 statusCodeText: Not Found statusCodeMessage: | bookingReference not found providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 errorDateTime: '2024-09-04T09:41:00Z' errors: - errorCode: 7003 errorCodeText: bookingReference Not Found errorCodeMessage: | The Booking does not exist notFoundAmendmentExample: summary: | Missing amended Booking description: | Cancelling the `Amendment` is requested - but no `Amended Booking` exists. **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" value: - httpMethod: GET - requestUri: /v2/bookings/cbrr-123?amendedContent=true + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 statusCode: 404 statusCodeText: Not Found statusCodeMessage: No amended booking exists providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 errorDateTime: '2024-09-04T09:41:00Z' errors: - errorCode: 7003 errorCodeText: No amended booking errorCodeMessage: No amended booking available Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies that the httpMethod in the error examples for the PATCH operation is wrongly set to GET. Correcting this improves the accuracy and clarity of the API documentation.	Low
General	Add Retry-After header to 202 response Add a Retry-After header to the 202 Accepted response for the GET /v3/shipping-instructions/{documentReference} endpoint to guide clients on when to retry the request. ebl/v3/EBL_v3.0.3.yaml [582-803] + get: + tags: + - Shipping Instructions + summary: | + Gets the Shipping Instructions + operationId: get-shipping-instructions + parameters: + - $ref: '#/components/parameters/documentReference' + - $ref: '#/components/parameters/updatedContent' + - $ref: '#/components/parameters/Api-Version-Major' + description: | ... + In case a previous request is being processed by the provider - a `202` (Accepted) with **no payload** can be used as a response until the processing is finished. + responses: + '200': ... + '202': + description: | -+ The `Shipping Instructions` is currently being processed by the provider. No payload is returned. A new `GET` request has to be made periodically to check if the provider has finished processing the `Shipping Instructions`. ++ The `Shipping Instructions` is currently being processed by the provider. No payload is returned. The client should wait for the duration specified in the `Retry-After` header before retrying the request. + headers: + API-Version: + $ref: '#/components/headers/API-Version' ++ Retry-After: ++ description: The number of seconds to wait before retrying the request. ++ schema: ++ type: integer ++ example: 30 [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion improves the API design by proposing the use of the Retry-After header for the 202 Accepted response, which provides a better client experience for handling asynchronous processing and avoids arbitrary polling.	Medium
	Use 204 for empty responses For the PUT /v3/shipping-instructions/{documentReference} endpoint, change the 202 Accepted response with a null body to a 204 No Content response to correctly represent an empty payload. ebl/v3/EBL_v3.0.3.yaml [411-426] + responses: -+ '202': ++ '204': + description: | -+ The `Shipping Instructions` update has been successfully accepted by the provider. `shippingInstructionsStatus` does not change, `updatedShippingInstructionsStatus` is not set and response payload is empty. Further processing will be done by provider. ++ The `Shipping Instructions` update has been successfully accepted by the provider and is being processed asynchronously. No content is returned. + headers: + API-Version: + $ref: '#/components/headers/API-Version' -+ content: -+ application/json: -+ examples: -+ receivedExample: -+ summary: | -+ Shipping Instructions updated by consumer -+ description: | -+ An `Updated Shipping Instructions` received and accepted by provider, the `Updated Shipping Instructions` now awaits provider action, the `shippingInstructionStatus` does not change. -+ value: null [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies an inconsistency between the response description ("empty payload") and the example (value: null), proposing a change to 204 No Content which is a more semantically correct way to indicate a successful operation with no response body.	Low
	Clarify asynchronous state transition documentation Clarify the documentation for PATCH /v3/transport-documents/{transportDocumentReference} to accurately describe the asynchronous state transition from DRAFT to APPROVED, and then to ISSUED. ebl/v3/EBL_v3.0.3.yaml [1656-1687] + patch: + tags: + - Transport Document + summary: | + Approve a Transport Document + operationId: approve-transport-document + description: | + A way for the consumer to Approve the `Draft Transport Document`. This endPoint corresponds with **UseCase 7 - Approve Draft Transport Document**. + + ## Precondition + In order to approve a `Draft Transport Document`, the status of the `Transport Document` needs to be in status `DRAFT` + + ## Postcondition -+ The provider has received an approval from the consumer for a `Transport Document` that is in state `DRAFT`. ++ The provider has received an approval from the consumer for a `Transport Document` that is in state `DRAFT`. The `transportDocumentStatus` will change to `APPROVED`. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives an approval: + 1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided. + - all values provided have correct data type. + 3. An empty response is returned and the consumer now awaits further processing by the provider. + -+ Once processed, the `Transport Document` is `ISSUED` and a [Transport Document Notification](#/TransportDocumentNotification) is sent. In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the ++ Once processed, the `transportDocumentStatus` will be set to `APPROVED`. The provider will then proceed to issue the document, which will change the status to `ISSUED`. These status changes will be communicated via a [Transport Document Notification](#/TransportDocumentNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v3/transport-documents/{transportDocumentReference} + + endPoint to check if the `transportDocumentStatus` of the `Transport Document` has changed. [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 5 __ Why: The suggestion correctly points out a potential ambiguity in the documentation regarding the state transition from DRAFT to ISSUED and proposes a clarification that improves the accuracy and clarity of the API documentation for consumers.	Low
	Fix incorrect method in description Update the description for the tooManyRequestsExample under the PUT /v2/bookings/{bookingReference} default response to reference the PUT method instead of GET. bkg/v2/BKG_v2.0.4.yaml [1091-1101] tooManyRequestsExample: summary: | Updating too many Bookings requests description: | Calling the endPoint - GET /v2/bookings/cbrr-123 + PUT /v2/bookings/cbrr-123 too many times within a time period. **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" value: httpMethod: PUT requestUri: /v2/bookings/cbrr-123 statusCode: 429 ... [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 5 __ Why: The suggestion correctly points out an inconsistency in an example's description, where a PUT endpoint's example incorrectly refers to the GET method. This change improves documentation clarity and correctness.	Low
More