Create a new BKG 2.0.3 and EBL 3.0.2 patch

[HenrikHL]

PR Type

Enhancement

---

Description

• Create new patch versions for BKG 2.0.3 and EBL 3.0.2

• Add comprehensive eBL surrender API specification

• Update core eBL and BKG API definitions

• Implement surrender request/response workflow

---

Diagram Walkthrough

flowchart LR
  A["eBL Solution Platform"] -- "POST surrender request" --> B["Carrier API"]
  B -- "Process asynchronously" --> C["Carrier System"]
  C -- "POST surrender response" --> A
  D["BKG 2.0.3"] --> E["Updated Booking API"]
  F["EBL 3.0.2"] --> G["Updated eBL Core API"]
  F --> H["EBL Issuance API"]
  F --> I["EBL Surrender API"]

Loading

File Walkthrough

Relevant files

Enhancement

EBL_SUR_v3.0.2.yaml New eBL surrender API specification                                            ebl/v3/surrender/EBL_SUR_v3.0.2.yaml Complete OpenAPI specification for eBL surrender workflow Define surrender request and response endpoints Implement endorsement chain tracking for eBL transfers Add comprehensive error handling and validation schemas +565/-0  EBL_v3.0.2.yaml Core eBL API version update                                                            ebl/v3/EBL_v3.0.2.yaml Update core eBL API to version 3.0.2 +8887/-0 BKG_v2.0.3.yaml Booking API version update                                                              bkg/v2/BKG_v2.0.3.yaml Update booking API to version 2.0.3 +6888/-0 EBL_ISS_v3.0.2.yaml eBL issuance API version update                                                    ebl/v3/issuance/EBL_ISS_v3.0.2.yaml Update eBL issuance API to version 3.0.2 +3471/-0

---

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Spec Consistency API-Version header example shows 3.0.1 while spec info.version is 3.0.2. Ensure header examples and changelog link reflect 3.0.2 for consistency. API-Version: schema: type: string example: 3.0.1 description: | SemVer used to indicate the version of the contract (API version) returned. parameters: Enum/Logic Validation For SurrenderRequestAnswer, comments are mandatory on rejection per description but not enforced by schema. Consider adding a conditional requirement or clarifying validation rules. SurrenderRequestAnswer: type: object title: Surrender Request Answer properties: surrenderRequestReference: type: string maxLength: 100 example: Z12345 pattern: ^\S(?:.*\S)?$ description: | The surrender request provided by the eBL solution in the surrender request. action: type: string description: | Action performed: - `SURR` (Surrendered) - `SREJ` (Surrender rejected) When the carrier accepts the surrender (`SURR`), the platform will inform the party that submitted the surrender request that the surrender has been accepted. If the surrender is due to an amendment, the carrier will follow up with issuing the amended document to the party that submitted the surrender. The carrier will immediately become the possessor of the bill and can now void it. When the carrier rejects the surrender (`SREJ`), the eBL is returned to the party that submitted the surrender request. enum: - SURR - SREJ example: SURR comments: type: string description: Free text comment associated with the surrender request transaction. Must be provided for rejections but should be omitted when accepting the surrender. maxLength: 255 pattern: ^\S(?:.*\S)?$ example: Comments... required: - surrenderRequestReference - action External Links Changelog anchor references v3.0.1 in the URL fragment; verify the link and anchor are correct for 3.0.2 to avoid broken documentation references. ### Changelog and GitHub For a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/surrender#v301). 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/).

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Require errorCode field Make errorCode required to ensure every detailed error includes a machine-parseable code as implied by the description and examples. This prevents incomplete error payloads that break consumers. ebl/v3/issuance/EBL_ISS_v3.0.2.yaml [294-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 [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly proposes making the errorCode field mandatory, which strengthens the API contract for error handling and aligns the schema with its description and example usage.	Medium
	Restrict platform codes via enum Enforce the documented allowed values for sendToPlatform via an enum to prevent invalid codes slipping through. This ensures strict validation consistent with the description. ebl/v3/issuance/EBL_ISS_v3.0.2.yaml [398-420] IssueToParty: - ... + type: object + title: Issue To Party + description: | + The party to whom the electronic Bill of Lading (eBL) must be issued. properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam sendToPlatform: type: string - pattern: ^\S+$ maxLength: 4 description: | - The eBL platform of the transaction party. - The value **MUST** be one of: - - `WAVE` (Wave) - - `CARX` (CargoX) - - `ESSD` (EssDOCS) - - `IDT` (ICE Digital Trade) - - `BOLE` (Bolero) - - `EDOX` (EdoxOnline) - - `IQAX` (IQAX) - - `SECR` (Secro) - - `TRGO` (TradeGO) - - `ETEU` (eTEU) - - `TRAC` (Enigio trace:original) - - `BRIT` (BRITC eBL) - - `COVA` (Covantis) - - `ETIT` (e-title) - - `KTNE` (KTNET) - - `CRED` (Credore) + The eBL platform of the transaction party. + The value MUST be one of the enumerated codes. + enum: + - WAVE + - CARX + - ESSD + - IDT + - BOLE + - EDOX + - IQAX + - SECR + - TRGO + - ETEU + - TRAC + - BRIT + - COVA + - ETIT + - KTNE + - CRED example: BOLE + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + required: + - partyName + - sendToPlatform + - identifyingCodes [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly recommends using an enum to enforce the allowed values for sendToPlatform, which makes the schema stricter and more self-documenting than a simple pattern.	Medium
	Correct HTTP method in example Fix the example method text under the PUT /v2/bookings/{bookingReference} default error block; it mistakenly shows GET. Incorrect method in examples can mislead integrators and automated example validators. bkg/v2/BKG_v2.0.3.yaml [1080-1099] default: description: | For other errors the error object should be populated with relevant information headers: API-Version: $ref: '#/components/headers/API-Version' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: 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. Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out a copy-paste error where an example description for the PUT endpoint incorrectly shows a GET request, and fixing it improves the clarity and correctness of the API documentation.	Low
	Align version header example Update the API-Version response header example to match this spec's version to avoid misleading clients and documentation drift. Keeping these aligned prevents confusion in automated contract tests and client generators. bkg/v2/BKG_v2.0.3.yaml [2245-2251] headers: API-Version: schema: type: string - example: 2.0.2 + example: 2.0.3 description: | SemVer used to indicate the version of the contract (API version) returned. Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies that the API-Version header example is 2.0.2 while the API version is 2.0.3, and fixing this inconsistency improves documentation accuracy.	Low
	Declare empty 202 response body For 202 responses with no payload, explicitly declare an empty body to avoid client/server content negotiation issues. Add a content section with no schema or set content to an empty object to signal no body. ebl/v3/EBL_v3.0.2.yaml [798-803] '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`. headers: API-Version: $ref: '#/components/headers/API-Version' + content: {} Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion correctly proposes to explicitly define an empty body for the 202 response, which improves the OpenAPI specification's clarity and prevents potential client-side issues.	Low
	Fix disclaimer grammar and clarity Fix grammar and clarity in the human-readable text to avoid ambiguity in legal disclaimers. Correct "exist is name only" to "exists in name only" and adjust phrasing for readability without changing meaning. ebl/v3/EBL_v3.0.2.yaml [1231-1253] termsAndConditions: | - You agree that this transport document exist is name only for the sake of + You agree that this transport document exists in name only for the sake of testing your conformance with the DCSA eBL API. This transport document is NOT backed by a real shipment with ANY carrier and NONE of the requested services will be carried out in real life. Unless required by applicable law or agreed to in writing, DCSA provides this JSON data on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing this JSON data and assume any risks associated with Your usage of this data. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall DCSA be liable to You for damages, including any direct, indirect, special, incidental, or - consequential damages of any character arising as a result of this terms or conditions + consequential damages of any character arising as a result of these terms and conditions or out of the use or inability to use the provided JSON data (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if DCSA has been advised of the possibility of such damages. Apply / Chat Suggestion importance[1-10]: 3 __ Why: The suggestion correctly identifies and fixes grammatical errors in the termsAndConditions example text, improving its professionalism and clarity.	Low
Possible issue	Tighten reference regex pattern The regex allows any non-whitespace and trailing spaces inside, which conflicts with API examples that are uppercase alphanumerics. Tighten the pattern to prevent leading/trailing spaces and constrain to allowed characters to reduce validation ambiguity. ebl/v3/EBL_v3.0.2.yaml [1198-1202] -pattern: ^\S(?:.*\S)?$ +pattern: ^[A-Z0-9\-]+$ 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. + A unique number allocated by the shipping line to the `Transport Document`. Uppercase letters, digits, and hyphen only; no spaces. example: HHL71800000 Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out that the regex pattern for transportDocumentReference is too broad and proposes a stricter pattern that aligns with the example value, improving data validation.	Low
	Fix header version mismatch Align the API-Version header example with the declared API version to avoid confusing clients and contract tests. Update the header example to 3.0.2. ebl/v3/issuance/EBL_ISS_v3.0.2.yaml [160-163] info: version: 3.0.2 title: DCSA eBL Issuance API ... components: headers: API-Version: schema: type: string - example: 3.0.1 + example: 3.0.2 [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies an inconsistency between the API version (3.0.2) and the header example (3.0.1), and fixing it improves the specification's clarity and consistency.	Low
More