Endorsement chain

[HenrikHL]

PR Type

Enhancement

---

Description

• Add DCSA eBL Endorsement Chain API v3.0.2

• Implement GET endpoint for endorsement chain retrieval

• Include comprehensive schema definitions and examples

• Add documentation and README for API usage

---

Diagram Walkthrough

flowchart LR
  API["eBL Endorsement Chain API"] --> GET["/endorsement-chains/{ref}"]
  GET --> Schema["EndorsementChainX Schema"]
  Schema --> Examples["Surrender Examples"]
  API --> README["Documentation"]

Loading

File Walkthrough

	Relevant files
Enhancement	EBL_END_3.0.2.yaml Add complete eBL Endorsement Chain API specification          ebl/v3/endorsement/EBL_END_3.0.2.yaml Complete OpenAPI 3.0.3 specification for eBL Endorsement Chain API Single GET endpoint for retrieving endorsement chains by transport document reference Comprehensive schema definitions for endorsement chain links, parties, and error responses Detailed examples showing surrendered straight B/L scenarios with and without on-behalf parties +846/-0
Documentation	README.md Add API documentation and README                                                  ebl/v3/endorsement/README.md Documentation for DCSA Bill of Lading Endorsement Chain API Links to SwaggerHub specification and related resources Version 3.0.2 release notes indicating initial release References to related Bill of Lading APIs and documentation +14/-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
⚪	No custom compliance provided Follow the guide to enable custom compliance check.
Update

Compliance status legend

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

[Copilot]

Pull Request Overview

This PR introduces a new "Endorsement Chain" API for electronic Bills of Lading (eBL), providing functionality to track the chain of endorsements and actions performed on transport documents throughout their lifecycle.

• Adds comprehensive OpenAPI specification for the eBL Endorsement Chain API
• Introduces GET endpoint for retrieving endorsement chains by transport document reference
• Includes detailed schema definitions for endorsement chain links, parties, and error responses

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
ebl/v3/endorsement/README.md	Introduces documentation for the new Endorsement Chain API with links to specifications and release notes
ebl/v3/endorsement/EBL_END_3.0.2.yaml	Complete OpenAPI specification defining the endorsement chain endpoint, request/response schemas, and comprehensive examples

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Consolidate redundant party schemas The schemas ActorParty, RecipientParty, RepresentedActorParty, and RepresentedRecipientParty are nearly identical and should be consolidated into a generic Party and RepresentedParty schema to reduce duplication. Examples: ebl/v3/endorsement/EBL_END_3.0.2.yaml [468-523] ActorParty: type: object title: Actor Party description: | Refers to a company or a legal entity. properties: partyName: type: string pattern: ^\S(?:.*\S)?$ maxLength: 70 ... (clipped 46 lines) ebl/v3/endorsement/EBL_END_3.0.2.yaml [524-579] RecipientParty: type: object title: Recipient Party description: | Refers to a company or a legal entity. properties: partyName: type: string pattern: ^\S(?:.*\S)?$ maxLength: 70 ... (clipped 46 lines) Solution Walkthrough: Before: components: schemas: ActorParty: properties: partyName: ... eblPlatform: ... identifyingCodes: ... representedParty: $ref: '#/components/schemas/RepresentedActorParty' RecipientParty: properties: partyName: ... eblPlatform: ... identifyingCodes: ... representedParty: $ref: '#/components/schemas/RepresentedRecipientParty' RepresentedActorParty: properties: partyName: ... identifyingCodes: ... RepresentedRecipientParty: properties: partyName: ... identifyingCodes: ... After: components: schemas: EndorsementChainLink: properties: ... actor: $ref: '#/components/schemas/Party' recipient: $ref: '#/components/schemas/Party' Party: properties: partyName: ... eblPlatform: ... identifyingCodes: ... representedParty: $ref: '#/components/schemas/RepresentedParty' RepresentedParty: properties: partyName: ... identifyingCodes: ... Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies significant structural duplication in the core data model and proposes a valid simplification that improves maintainability and adheres to API design best practices.	Medium
General	Enforce non-empty endorsement chain list Add minItems: 1 to the endorsementChain schema to enforce that the list must contain at least one action, as stated in its description. ebl/v3/endorsement/EBL_END_3.0.2.yaml [411-428] endorsementChain: type: array + minItems: 1 description: | A list of one or more actions that affect an eBL, starting from its issuance onward. It is equivalent to the "back side" of a physical Bill of Lading. The type of actions recorded in the endorsement chain as defined by the DCSA standard are listed below: - **Issue:** The act of issuing an eBL to the `Issue to` party, meaning the designated recipient of the action (typically the shipper or their on behalf of party). ... items: $ref: '#/components/schemas/EndorsementChainLink' [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly aligns the schema with its description by enforcing that the endorsementChain array cannot be empty, which reflects the business logic and improves the robustness of the API contract.	Medium
Possible issue	Enforce represented party identification codes In the RepresentedActorParty schema, make the identifyingCodes field required and ensure it contains at least one item by adding minItems: 1. ebl/v3/endorsement/EBL_END_3.0.2.yaml [580-597] RepresentedActorParty: type: object title: Represented Party description: The party on whose behalf the action was performed. properties: partyName: type: string pattern: ^\S(?:.*\S)?$ maxLength: 70 description: | Name of the party. example: Globeteam identifyingCodes: type: array + minItems: 1 items: $ref: '#/components/schemas/IdentifyingCode' required: - partyName + - identifyingCodes Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out an inconsistency and improves data integrity by making the RepresentedActorParty schema require identifyingCodes, aligning it with other party schemas in the file.	Low
	Require identification for represented recipients In the RepresentedRecipientParty schema, make the identifyingCodes field required and ensure it contains at least one item by adding minItems: 1. ebl/v3/endorsement/EBL_END_3.0.2.yaml [599-616] RepresentedRecipientParty: type: object title: Represented Party description: The party on whose behalf the action was directed. properties: partyName: type: string pattern: ^\S(?:.*\S)?$ maxLength: 70 description: | Name of the party. example: Globeteam identifyingCodes: type: array + minItems: 1 items: $ref: '#/components/schemas/IdentifyingCode' required: - partyName + - identifyingCodes Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies an inconsistency and improves data integrity by making the RepresentedRecipientParty schema require identifyingCodes, aligning it with other party schemas in the file.	Low
Update

[Copilot]

Pull Request Overview

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

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

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

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The documentation indicates ESSD is deprecated in favor of IDT, but both values are still listed as valid options. Consider adding a deprecation notice or removal timeline to clarify the migration path.

Suggested change

	- `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`)
	- `ESSD` (EssDOCS - **Deprecated**: This value has been deprecated in favor of `IDT`. Support for `ESSD` will be removed in a future version. Please migrate to `IDT` as soon as possible.)

[Copilot]

Similar to the ActorParty schema, the RecipientParty schema also lists ESSD as deprecated but still valid. Consider consistent handling of deprecated values across all party schemas.

[Copilot]

The IdentifyingCode schema also includes the deprecated ESSD value. For consistency, all schemas referencing eBL platforms should handle the ESSD deprecation uniformly.