BKG 2.0, EBL 3.0: SD-3041: Display specific text in the visualisation of negotiable BLs

[HenrikHL]

SD-3041: Display specific text in the visualisation of negotiable BLs

[qodo-code-review]

PR Summary by Qodo

Add displayed to-order text across eBL 3.0 APIs

✨ Enhancement 📝 Documentation 🕐 10-20 Minutes

AI Description

• Adds ordered display text for endorsee representation on negotiable bills of lading.
• Applies constraints and precedence consistently across eBL, issuance, and PINT contracts.

Diagram

graph TD
  CREATE["Create SI"] --> TEXT["To-order text"] --> TD["Transport document"] --> ISS["Issuance contract"]
  UPDATE["Update SI"] --> TEXT
  CURRENT["Shipping instructions"] --> TEXT
  TD --> PINT["PINT contract"]

Loading

High-Level Assessment

Adding the field directly to each affected bundled contract is appropriate because the specifications are independently published and must remain self-contained. A reusable component was considered, but it would add indirection and would not eliminate duplication across separate specification files.

Files changed (3) +96 / -0

Enhancement (3) +96 / -0

EBL_v3.0.4.yamlExpose displayed to-order text throughout the core eBL contract +64/-0

Expose displayed to-order text throughout the core eBL contract

• Adds 'displayedToOrderText' to Create Shipping Instructions, Update Shipping Instructions, Shipping Instructions, and Transport Document schemas. The field supports up to six ordered 35-character lines, applies only to to-order bills, and takes visual precedence over supplied endorsee party details.

ebl/v3/EBL_v3.0.4.yaml

EBL_ISS_v3.0.4.yamlInclude displayed to-order text in issuance payloads +16/-0

Include displayed to-order text in issuance payloads

• Extends the issuance Transport Document schema with the same constrained display text and precedence rules, ensuring issued negotiable bills can represent an endorsee without detailed party information.

ebl/v3/issuance/EBL_ISS_v3.0.4.yaml

EBL_PINT_v3.0.0.yamlCarry displayed to-order text through PINT transfers +16/-0

Carry displayed to-order text through PINT transfers

• Adds the display-only endorsee text to the PINT Transport Document schema, preserving ordered lines and consistent negotiable-bill semantics during document transfer.

pint/v3/EBL_PINT_v3.0.0.yaml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

1. PINT endorsement classification conflicts 🐞 Bug ≡ Correctness

Description

displayedToOrderText may replace documentParties.endorsee, but PINT still defines every
isToOrder=true document without that party as blank-endorsed and requires the party for a to-order
eBL. A text-only order is therefore classified inconsistently, leading implementations to reject it
or apply divergent endorsement handling.

Code

pint/v3/EBL_PINT_v3.0.0.yaml[1763]

+            Text to be displayed in the Transport Document visualisation of a negotiable BL to represent the endorsee, typically shown in the consignee field in the traditional BL layout. This attribute can be used instead of providing endorsee party details when no specific information (e.g. address, contact details) should be displayed.

Evidence

The added property explicitly permits omitting endorsee party details, while PINT's API-level rules
classify absence of that party as blank endorsement and require its presence for a
to-order/negotiable eBL.

pint/v3/EBL_PINT_v3.0.0.yaml[20-25]
pint/v3/EBL_PINT_v3.0.0.yaml[1760-1769]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`displayedToOrderText` can replace endorsee party details, but PINT's introductory classification still determines blank endorsement and to-order status exclusively from the presence of `documentParties.endorsee`.

## Issue Context
Clarify whether text-only orders are equivalent to a named endorsee or remain blank-endorsed presentation overrides, then make the schema description and PINT classification rules agree.

## Fix Focus Areas
- pint/v3/EBL_PINT_v3.0.0.yaml[20-25]
- pint/v3/EBL_PINT_v3.0.0.yaml[1760-1769]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Missing mixed-version downgrade rule ✓ Resolved 🐞 Bug ☼ Reliability

Description

The new field may replace the endorsee party without defining behavior for v3.0.3-or-earlier peers,
even though requests negotiate only major version 3. An older peer can ignore the unknown text and
interpret the missing endorsee as blank endorsement, producing a different visualization or document
classification.

Code

ebl/v3/EBL_v3.0.4.yaml[4407]

+            Text to be displayed in the Transport Document visualisation of a negotiable BL to represent the endorsee, typically shown in the consignee field in the traditional BL layout. This attribute can be used instead of providing endorsee party details when no specific information (e.g. address, contact details) should be displayed.

Evidence

Requests expose only the major API version, the new property permits omitting endorsee details, and
the existing contract defines an isToOrder document without an endorsee as blank-endorsed. Nearby
compatibility notes show that this API already requires explicit guards when newer 3.0.x content may
be ignored by older implementations.

ebl/v3/EBL_v3.0.4.yaml[3721-3729]
ebl/v3/EBL_v3.0.4.yaml[4262-4268]
ebl/v3/EBL_v3.0.4.yaml[4404-4413]
ebl/v3/EBL_v3.0.4.yaml[4131-4132]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Using `displayedToOrderText` without an endorsee party is unsafe when communicating with pre-3.0.4 implementations because patch versions cannot be selected through the request version header.

## Issue Context
Add an explicit compatibility rule, such as prohibiting text-only replacement for older peers or requiring an endorsee fallback. Apply equivalent guidance wherever the property is exchanged.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[4404-4413]
- ebl/v3/EBL_v3.0.4.yaml[4741-4750]
- ebl/v3/EBL_v3.0.4.yaml[5102-5111]
- ebl/v3/EBL_v3.0.4.yaml[10103-10112]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1101-1110]
- pint/v3/EBL_PINT_v3.0.0.yaml[1760-1769]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}