EBL 3.0: SD-3041: Move displayedToOrderText next to isToOrder

[HenrikHL]

SD-3041: Move displayedToOrderText next to isToOrder

[qodo-code-review]

PR Summary by Qodo

Move displayedToOrderText adjacent to isToOrder in EBL 3.0 specs

📝 Documentation 🕐 10-20 Minutes

AI Description

• Reorder schema fields so displayedToOrderText sits next to isToOrder.
• Apply the same ordering in EBL, Issuance, and PINT OpenAPI specs.
• Improve spec readability without changing validation semantics.

Diagram

graph TD
  F["EBL_v3.0.4.yaml"] --> A["EBL 3.0 specs"]
  G["EBL_ISS_v3.0.4.yaml"] --> A
  H["EBL_PINT_v3.0.0.yaml"] --> A
  A --> B["TransportDocument schema"] --> D["isToOrder"] --> E["displayedToOrderText"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Deduplicate displayedToOrderText via shared component schema ($ref)

• ➕ Eliminates repeated inline schema blocks across multiple specs/sections
• ➕ Reduces risk of future drift in descriptions/constraints (maxItems/maxLength)
• ➕ Makes future edits to the field definition single-source
• ➖ Requires introducing and wiring a new component schema in each spec
• ➖ May be considered a larger structural change than the ticket’s scope
• ➖ Slightly less readable inline for people skimming the immediate schema

Recommendation: The current approach is appropriate for SD-3041: it improves readability by placing displayedToOrderText next to the controlling flag (isToOrder) without altering the contract. Consider the $ref-based deduplication as a follow-up cleanup if schema drift becomes a recurring problem.

Files changed (3) +96 / -96

Documentation (3) +96 / -96

EBL_v3.0.4.yamlReorder displayedToOrderText to follow isToOrder in multiple schemas +64/-64

Reorder displayedToOrderText to follow isToOrder in multiple schemas

• Moves the 'displayedToOrderText' array definition from below 'documentParties' to directly after 'isToOrder' in several component schema sections. Content and constraints of the property remain unchanged; only placement/order in the YAML is updated for readability.

ebl/v3/EBL_v3.0.4.yaml

EBL_ISS_v3.0.4.yamlAlign Issuance spec field ordering for displayedToOrderText +16/-16

Align Issuance spec field ordering for displayedToOrderText

• Repositions 'displayedToOrderText' so it appears adjacent to 'isToOrder' instead of later in the schema block. This is a non-functional documentation/structure change in the Issuance OpenAPI spec.

ebl/v3/issuance/EBL_ISS_v3.0.4.yaml

EBL_PINT_v3.0.0.yamlAlign PINT spec field ordering for displayedToOrderText +16/-16

Align PINT spec field ordering for displayedToOrderText

• Moves 'displayedToOrderText' to sit next to 'isToOrder' in the relevant schema definition. The property definition text and validation constraints are preserved; only ordering is changed.

pint/v3/EBL_PINT_v3.0.0.yaml

[qodo-code-review]

Code Review by Qodo

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

1. displayedToOrderText not gated by isToOrder 📎 Requirement gap ≡ Correctness

Description

The schema defines displayedToOrderText as a regular optional root property, so payloads can
include it even when isToOrder=false because no schema-level restriction ties the two fields. This
violates the requirement that displayedToOrderText is only permitted when isToOrder=true.

Code

ebl/v3/EBL_v3.0.4.yaml[R4269-4272]

+        displayedToOrderText:
+          type: array
+          description: |
+            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

PR Compliance ID 3 requires restricting displayedToOrderText usage to cases where isToOrder is
true, but in the relevant schemas (including CreateShippingInstructions / issuance / PINT)
displayedToOrderText is declared as a normal optional property under properties: adjacent to
isToOrder without any conditional or structural constraint that would prevent it from being
present when isToOrder is false, demonstrating the schema currently permits the forbidden
combination.

Conditionally allow Displayed To Order Text only when isToOrder is true
ebl/v3/EBL_v3.0.4.yaml[4262-4284]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[807-829]
pint/v3/EBL_PINT_v3.0.0.yaml[1466-1488]

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` is documented as only applicable when `isToOrder=TRUE`, but the OpenAPI schemas currently allow it to be provided regardless of the value of `isToOrder`.

## Issue Context
PR Compliance ID 3 requires that `Displayed To Order Text` is only permitted/processed when `isToOrder` is true, so the schema should enforce that `displayedToOrderText` cannot appear unless `isToOrder=true`.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[4262-4284]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[807-829]
- pint/v3/EBL_PINT_v3.0.0.yaml[1466-1488]

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

---

Context sources

✅ Tickets: 🎫 Add support in EBL (SI, TD), ISS & PINT to display specific text in the visualisation of negotiable BLs [CMA request]

Review mode: ⚖️ Balanced: This is a behavior-affecting public OpenAPI schema change replicated across several contract files; despite being largely relocational, correctness of field placement and consistency warrants a complete single-pass review.

Tip of the day

💡 Did you know, you can switch off images and animations for a plain-text comment

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. displayedtoordertext not gated by istoorder 📎 Requirement gap ≡ Correctness

The schema defines displayedToOrderText as a regular optional root property, so payloads can
include it even when isToOrder=false because no schema-level restriction ties the two fields. This
violates the requirement that displayedToOrderText is only permitted when isToOrder=true.

Agent Prompt

## Issue description
`displayedToOrderText` is documented as only applicable when `isToOrder=TRUE`, but the OpenAPI schemas currently allow it to be provided regardless of the value of `isToOrder`.

## Issue Context
PR Compliance ID 3 requires that `Displayed To Order Text` is only permitted/processed when `isToOrder` is true, so the schema should enforce that `displayedToOrderText` cannot appear unless `isToOrder=true`.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[4262-4284]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[807-829]
- pint/v3/EBL_PINT_v3.0.0.yaml[1466-1488]

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