EBL 3.0: Preparation for eBL patches (eBL, ISS and SUR)

[HenrikHL]

User description

Create empty "placeholders" for patches
Only content changed is the version number (and the link to a "What's new" section - which is not written yet)

---

PR Type

enhancement, documentation

---

Description

• Added new OpenAPI YAML specs for eBL Surrender API v3.0.1 and v3.0.2.

• Updated API versioning and documentation links for new patch versions.

• Introduced placeholders for upcoming eBL, ISS, and SUR patch releases.

• Ensured version-specific documentation and changelog references.

---

Changes walkthrough 📝

Relevant files

Documentation

EBL_SUR_v3.0.1.yaml Add eBL Surrender API OpenAPI spec v3.0.1                                ebl/v3/surrender/EBL_SUR_v3.0.1.yaml Added OpenAPI 3.0.3 specification for eBL Surrender API v3.0.1. Included endpoints for surrender requests and responses. Provided detailed schema definitions and error handling. Linked to version-specific documentation and changelog. +558/-0  EBL_SUR_v3.0.2.yaml Add eBL Surrender API OpenAPI spec v3.0.2                                ebl/v3/surrender/EBL_SUR_v3.0.2.yaml Added OpenAPI 3.0.3 specification for eBL Surrender API v3.0.2. Updated API version, server URL, and changelog links. Maintained endpoints and schema consistency with v3.0.1. Prepared for future patch-specific documentation. +558/-0  EBL_v3.0.2.yaml Add placeholder for eBL API v3.0.2                                              ebl/v3/EBL_v3.0.2.yaml Added placeholder for eBL API v3.0.2 specification. Updated version number and documentation links. +8828/-0 EBL_ISS_v3.0.1.yaml Add placeholder for eBL Issuance API v3.0.1                            ebl/v3/issuance/EBL_ISS_v3.0.1.yaml Added placeholder for eBL Issuance API v3.0.1 specification. Set up versioning and documentation references. +3466/-0 EBL_ISS_v3.0.2.yaml Add placeholder for eBL Issuance API v3.0.2                            ebl/v3/issuance/EBL_ISS_v3.0.2.yaml Added placeholder for eBL Issuance API v3.0.2 specification. Updated version and documentation links. +3466/-0

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Version References The changelog URL on line 38 points to a v3.0.1 section that may not exist yet. Verify that the referenced GitHub changelog section has been created. 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). Version References The changelog URL on line 38 points to a v3.0.2 section that may not exist yet. Verify that the referenced GitHub changelog section has been created. For a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/surrender#v302). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us).

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix schema reference format The schema reference to IssuanceManifest is incorrectly formatted. It should use the proper OpenAPI schema reference format with '#/components/schemas/IssuanceManifest' instead of '#/IssuanceManifest' to correctly link to the schema definition. ebl/v3/issuance/EBL_ISS_v3.0.2.yaml [314-322] issuanceManifestSignedContent: type: string pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ description: | - JWS content with compact serialization according to [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515#section-7.1). JWS-signed payload is defined in schema [IssuanceManifest](#/IssuanceManifest). + JWS content with compact serialization according to [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515#section-7.1). JWS-signed payload is defined in schema [IssuanceManifest](#/components/schemas/IssuanceManifest). This attribute is used to provide integrity of various parts of the payload that enable parties to validate whether a payload matches what the carrier issued originally. Accordingly, the payload is signed by the carrier. # TODO: Update example Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies an improper OpenAPI schema reference format. The reference #/IssuanceManifest should be #/components/schemas/IssuanceManifest to properly link to the schema definition, which could impact documentation generation and validation tools.	Medium
	Fix schema reference format The schema reference to IssuanceManifest is incorrectly formatted. It should use the proper OpenAPI schema reference format with '#/components/schemas/IssuanceManifest' instead of '#/IssuanceManifest' to correctly link to the schema definition. ebl/v3/issuance/EBL_ISS_v3.0.1.yaml [318] issuanceManifestSignedContent: type: string pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ description: | - JWS content with compact serialization according to [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515#section-7.1). JWS-signed payload is defined in schema [IssuanceManifest](#/IssuanceManifest). + JWS content with compact serialization according to [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515#section-7.1). JWS-signed payload is defined in schema [IssuanceManifest](#/components/schemas/IssuanceManifest). This attribute is used to provide integrity of various parts of the payload that enable parties to validate whether a payload matches what the carrier issued originally. Accordingly, the payload is signed by the carrier. # TODO: Update example [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies an improperly formatted schema reference. OpenAPI specifications require schema references to use the format #/components/schemas/SchemaName for proper linking and tool compatibility.	Low
Security	Add security scheme definition The API specification is missing a security scheme definition, which is critical for an eBL (electronic Bill of Lading) API. For a document as legally significant as a Bill of Lading, proper authentication and authorization mechanisms are essential to ensure data integrity and non-repudiation. ebl/v3/EBL_v3.0.2.yaml [1-4] openapi: 3.0.3 info: version: 3.0.2 title: DCSA Shipping Instructions and Transport Document API +security: + - bearerAuth: [] Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the API specification lacks security definitions, which is important for an eBL API handling legally significant documents. However, security schemes can be implemented at infrastructure level and may not be required in the specification itself.	Low
More