BKG 2.0, EBL 3.0: SD-3100, SD-3101: Update equipmentAttributeCode description and example by HenrikHL · Pull Request #648 · dcsaorg/DCSA-OpenAPI

HenrikHL · 2026-08-20T15:49:51Z

SD-3100: Add support for identification of plastic pellets shipments
SD-3101: Add support for identification of plastic pellets shipments

…cription and example

qodo-code-review · 2026-08-20T15:50:52Z

PR Summary by Qodo

Clarify and expand equipmentAttributeCodes for plastic pellet shipments (BKG/EBL)

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Expand equipmentAttributeCodes description to include plastic pellets and other equipment
 characteristics.
• Provide multi-value examples (e.g., PLX/FDG/FLX) for clearer implementer guidance.
• Reposition equipmentAttributeCodes in EBL schemas to align with cargo-item modeling.

Diagram

graph TD
  C["API clients"] --> B["BKG v2.0.5 OpenAPI"] --> S{{"SMDG ATTRIBUTES"}}
  C --> E["EBL v3.0.4 OpenAPI"] --> S
  C --> I["EBL ISS v3.0.4 OpenAPI"] --> S
  C --> P["EBL PINT v3.0.0 OpenAPI"] --> S

High-Level Assessment

The following are alternative approaches to this PR:

1. Define a reusable schema component for EquipmentAttributeCodes

➕ Eliminates repeated description/example blocks across BKG/EBL/ISS/PINT
➕ Ensures future wording/example updates stay consistent
➕ Makes it clearer that all variants share the same semantics and code list
➖ Requires minor refactoring of the OpenAPI schemas to introduce and reference the shared component
➖ May be harder for readers who prefer fully inlined schema documentation

2. Keep equipmentAttributeCodes only on Utilized Transport Equipment (UTE)

➕ Models the data strictly where the attribute applies (the equipment)
➕ Avoids potential confusion about whether codes apply per cargo item vs per equipment
➖ Does not match the PR’s apparent intent to associate codes with cargo items
➖ Could reduce expressiveness if different cargo items in the same UTE need different attributes

Recommendation: The PR’s approach (explicitly documenting plastic pellet and similar equipment characteristics, plus providing multi-value examples) is a clear improvement for implementers. If this pattern will continue across specs/versions, consider extracting a shared OpenAPI component for equipmentAttributeCodes to reduce duplication and prevent semantic drift.

Files changed (4) +62 / -38

Enhancement (3) +52 / -36

EBL_v3.0.4.yamlAdd cargo-item equipmentAttributeCodes with expanded description; remove older placement +26/-18

Add cargo-item equipmentAttributeCodes with expanded description; remove older placement

• Introduces 'equipmentAttributeCodes' on the cargo item with updated semantics referencing the SMDG Attributes code list and plastic pellet use case. Removes the previous 'equipmentAttributeCodes' block from another schema location to align modeling and avoid inconsistent wording.

ebl/v3/EBL_v3.0.4.yaml

EBL_ISS_v3.0.4.yamlAlign issuance schema: cargo-item equipmentAttributeCodes + updated examples +13/-9

Align issuance schema: cargo-item equipmentAttributeCodes + updated examples
• Adds 'equipmentAttributeCodes' to the cargo item in the issuance schema with clarified wording and a multi-value example list. Removes the older 'equipmentAttributeCodes' block from the prior location to match the updated EBL modeling.
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml

EBL_PINT_v3.0.0.yamlAlign PINT schema: cargo-item equipmentAttributeCodes + updated examples +13/-9

Align PINT schema: cargo-item equipmentAttributeCodes + updated examples

• Adds 'equipmentAttributeCodes' to the cargo item with expanded description (including plastic pellets and related equipment characteristics) and multiple example values. Removes the older 'equipmentAttributeCodes' definition from the previous schema location for consistency.

pint/v3/EBL_PINT_v3.0.0.yaml

Documentation (1) +10 / -2

BKG_v2.0.5.yamlClarify equipmentAttributeCodes meaning and add multi-value examples +10/-2

Clarify equipmentAttributeCodes meaning and add multi-value examples

• Updates the equipment attribute code description to include properties/characteristics (e.g., plastic pellets, food grade, flexitank). Adds an array-style example list (PLX/FDG/FLX) to better illustrate expected values.

bkg/v2/BKG_v2.0.5.yaml

qodo-code-review · 2026-08-20T15:54:45Z

Code Review by Qodo

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

1. equipmentAttributeCodes on wrong schema ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

equipmentAttributeCodes was moved from CargoItem/CargoItemShipper to
ConsignmentItem/ConsignmentItemShipper, but compliance requires it at cargoItem level for SI
create/update, responses, and notifications. This also makes the payload ambiguous because a
ConsignmentItem can cover multiple CargoItems/containers while the codes are described as
applying to the Utilized Transport Equipment, and the removal is backward-incompatible for existing
producers/consumers expecting the field on CargoItem.

Code

ebl/v3/EBL_v3.0.4.yaml[R7754-7757]

+        equipmentAttributeCodes:
+          type: array
+          description: |
+            A list of `Equipment Attribute Codes` that apply to the cargo item.

Evidence
The cited schemas show ConsignmentItem contains a cargoItems array (so it can span multiple
CargoItems/containers) while equipmentAttributeCodes is introduced at the consignment-item
level, even though the codes are described as applying to Utilized Transport Equipment and the
consignment item itself does not provide a single equipment identifier; by contrast, the
per-container granularity exists on CargoItem via equipmentReference. The CargoItem schema
sections referenced no longer include equipmentAttributeCodes (jumping from equipmentReference
to other cargo metrics), and the same removal pattern is indicated for the issuance and PINT
specifications, which together demonstrates both non-compliance with PR Compliance IDs (requiring
cargoItem.equipmentAttributeCodes, including for PLX) and a breaking change for implementations
that already send/expect the field at cargo-item level.
EBL (SI) API adds optional cargoItem.equipmentAttributeCodes array across requests, responses, and notifications
ebl/v3/EBL_v3.0.4.yaml[7754-7795]
ebl/v3/EBL_v3.0.4.yaml[8178-8299]
ebl/v3/EBL_v3.0.4.yaml[7664-7669]
ebl/v3/EBL_v3.0.4.yaml[7754-7762]
ebl/v3/EBL_v3.0.4.yaml[8178-8193]
ebl/v3/EBL_v3.0.4.yaml[8178-8206]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1602-1621]
pint/v3/EBL_PINT_v3.0.0.yaml[2261-2279]
ebl/v3/EBL_v3.0.4.yaml[8236-8299]
ebl/v3/EBL_v3.0.4.yaml[7754-7773]

Agent prompt

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

## Issue description
`equipmentAttributeCodes` is currently defined on `ConsignmentItem`/`ConsignmentItemShipper` and removed from `CargoItem`/`CargoItemShipper`, but compliance requires it to be exposed as `cargoItem.equipmentAttributeCodes` across SI request/response/notification schemas and it must be associable with the specific utilized transport equipment (container) identified by `equipmentReference`. The current modeling is ambiguous because a `ConsignmentItem` can include multiple `cargoItems` (multiple containers) while the codes are described as equipment-specific, and the removal from `CargoItem` is a backward-incompatible change that will break existing producers/consumers.

## Issue Context
- In `EBL_v3.0.4.yaml`, `ConsignmentItem` contains a `cargoItems` array, so placing `equipmentAttributeCodes` at consignment-item level cannot unambiguously indicate which container(s)/equipment the codes apply to.
- `CargoItem` is the scope where `equipmentReference` exists (single-equipment granularity) and is described as the smallest unit used by stuffing, making it the correct place to attach equipment-related attributes such as values like `PLX`.
- PR Compliance IDs referenced in the evidence require `cargoItem.equipmentAttributeCodes` (including for PLX) in SI request/response/notification models; the current PR instead adds the field under consignment items and removes it from cargo items.
- The same removal/placement pattern is indicated for issuance and PINT schemas, increasing interoperability and validation failure risk across specs.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[7664-7766]
- ebl/v3/EBL_v3.0.4.yaml[7754-7960]
- ebl/v3/EBL_v3.0.4.yaml[8178-8330]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1379-1395]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1602-1648]
- pint/v3/EBL_PINT_v3.0.0.yaml[2038-2054]
- pint/v3/EBL_PINT_v3.0.0.yaml[2261-2308]

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

2. ~~Whitespace in example code~~ ✓ Resolved 🐞 Bug ≡ Correctness ⭐ New

Description

The array example includes FLX  with a trailing space; clients copying examples (or tooling that
preserves raw scalars) can end up sending a different value than intended, leading to
invalid/unknown equipmentAttributeCodes. This same typo is duplicated across EBL, EBL Issuance, and
PINT specs.

Code

ebl/v3/EBL_v3.0.4.yaml[R9089-9091]

+            - PLX
+            - FDG
+            - FLX

Evidence
In all three updated specifications, the equipmentAttributeCodes property-level example list
includes an FLX entry with a trailing space, visible directly in the YAML content at the cited
lines.
ebl/v3/EBL_v3.0.4.yaml[9088-9091]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[2335-2338]
pint/v3/EBL_PINT_v3.0.0.yaml[2994-2997]

Agent prompt

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

## Issue description
The OpenAPI `example` for `equipmentAttributeCodes` contains a trailing whitespace in the `FLX` entry (`"FLX "`). This can be copied verbatim by API consumers or propagated by documentation/codegen tooling, resulting in an incorrect attribute code value.

## Issue Context
The same example list is duplicated across multiple YAML specs.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[9088-9091]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[2335-2338]
- pint/v3/EBL_PINT_v3.0.0.yaml[2994-2997]

## Suggested fix
Change `- FLX ` to `- FLX` (and optionally quote the values, e.g. `- "FLX"`, to avoid any whitespace ambiguity).

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

Context sources

✅ Tickets: 🎫 Update BKG API: Add support for identification of plastic pellets shipments in Booking request 🎫 Update EBL (SI) API: Add support for identification of plastic pellets shipments in Shipping Instructions

Tip of the day

💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit 48bd037

Results up to commit 9a7cbd4 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. equipmentAttributeCodes on wrong schema ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

equipmentAttributeCodes was moved from CargoItem/CargoItemShipper to
ConsignmentItem/ConsignmentItemShipper, but compliance requires it at cargoItem level for SI
create/update, responses, and notifications. This also makes the payload ambiguous because a
ConsignmentItem can cover multiple CargoItems/containers while the codes are described as
applying to the Utilized Transport Equipment, and the removal is backward-incompatible for existing
producers/consumers expecting the field on CargoItem.

Code

ebl/v3/EBL_v3.0.4.yaml[R7754-7757]

+        equipmentAttributeCodes:
+          type: array
+          description: |
+            A list of `Equipment Attribute Codes` that apply to the cargo item.

Evidence
The cited schemas show ConsignmentItem contains a cargoItems array (so it can span multiple
CargoItems/containers) while equipmentAttributeCodes is introduced at the consignment-item
level, even though the codes are described as applying to Utilized Transport Equipment and the
consignment item itself does not provide a single equipment identifier; by contrast, the
per-container granularity exists on CargoItem via equipmentReference. The CargoItem schema
sections referenced no longer include equipmentAttributeCodes (jumping from equipmentReference
to other cargo metrics), and the same removal pattern is indicated for the issuance and PINT
specifications, which together demonstrates both non-compliance with PR Compliance IDs (requiring
cargoItem.equipmentAttributeCodes, including for PLX) and a breaking change for implementations
that already send/expect the field at cargo-item level.
EBL (SI) API adds optional cargoItem.equipmentAttributeCodes array across requests, responses, and notifications
ebl/v3/EBL_v3.0.4.yaml[7754-7795]
ebl/v3/EBL_v3.0.4.yaml[8178-8299]
ebl/v3/EBL_v3.0.4.yaml[7664-7669]
ebl/v3/EBL_v3.0.4.yaml[7754-7762]
ebl/v3/EBL_v3.0.4.yaml[8178-8193]
ebl/v3/EBL_v3.0.4.yaml[8178-8206]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1602-1621]
pint/v3/EBL_PINT_v3.0.0.yaml[2261-2279]
ebl/v3/EBL_v3.0.4.yaml[8236-8299]
ebl/v3/EBL_v3.0.4.yaml[7754-7773]

Agent prompt

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

## Issue description
`equipmentAttributeCodes` is currently defined on `ConsignmentItem`/`ConsignmentItemShipper` and removed from `CargoItem`/`CargoItemShipper`, but compliance requires it to be exposed as `cargoItem.equipmentAttributeCodes` across SI request/response/notification schemas and it must be associable with the specific utilized transport equipment (container) identified by `equipmentReference`. The current modeling is ambiguous because a `ConsignmentItem` can include multiple `cargoItems` (multiple containers) while the codes are described as equipment-specific, and the removal from `CargoItem` is a backward-incompatible change that will break existing producers/consumers.

## Issue Context
- In `EBL_v3.0.4.yaml`, `ConsignmentItem` contains a `cargoItems` array, so placing `equipmentAttributeCodes` at consignment-item level cannot unambiguously indicate which container(s)/equipment the codes apply to.
- `CargoItem` is the scope where `equipmentReference` exists (single-equipment granularity) and is described as the smallest unit used by stuffing, making it the correct place to attach equipment-related attributes such as values like `PLX`.
- PR Compliance IDs referenced in the evidence require `cargoItem.equipmentAttributeCodes` (including for PLX) in SI request/response/notification models; the current PR instead adds the field under consignment items and removes it from cargo items.
- The same removal/placement pattern is indicated for issuance and PINT schemas, increasing interoperability and validation failure risk across specs.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[7664-7766]
- ebl/v3/EBL_v3.0.4.yaml[7754-7960]
- ebl/v3/EBL_v3.0.4.yaml[8178-8330]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1379-1395]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1602-1648]
- pint/v3/EBL_PINT_v3.0.0.yaml[2038-2054]
- pint/v3/EBL_PINT_v3.0.0.yaml[2261-2308]

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

HenrikHL · 2026-08-20T20:41:44Z

/agentic_review

qodo-code-review · 2026-08-20T20:44:38Z

Code review by qodo was updated up to the latest commit 942f381

HenrikHL · 2026-08-20T20:52:25Z

/agentic_review

qodo-code-review · 2026-08-20T20:54:14Z

Code review by qodo was updated up to the latest commit 48bd037

BKG 2.0, EBL 3.0: SD-3100, SD-3101: Update equipmentAttributeCode des…

9a7cbd4

…cription and example

qodo-code-review Bot reviewed Aug 20, 2026

View reviewed changes

Comment thread ebl/v3/EBL_v3.0.4.yaml Outdated

Move equipmentAttributeCodes

942f381

qodo-code-review Bot reviewed Aug 20, 2026

View reviewed changes

Comment thread ebl/v3/EBL_v3.0.4.yaml Outdated

Remove trailing space

48bd037

HenrikHL merged commit e5f9fff into master Aug 20, 2026
1 check passed

HenrikHL deleted the SD-3100_SD-3101_Update-equipmentAttributeCodes branch August 20, 2026 20:58

Navigation Menu

Uh oh!

BKG 2.0, EBL 3.0: SD-3100, SD-3101: Update equipmentAttributeCode description and example - #648

BKG 2.0, EBL 3.0: SD-3100, SD-3101: Update equipmentAttributeCode description and example#648
HenrikHL merged 3 commits into
masterfrom
SD-3100_SD-3101_Update-equipmentAttributeCodes

HenrikHL commented Aug 20, 2026 •

edited by atlassian Bot

Loading

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

Uh oh!

qodo-code-review Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

HenrikHL commented Aug 20, 2026

Uh oh!

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

Uh oh!

HenrikHL commented Aug 20, 2026

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

HenrikHL commented Aug 20, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

PR Summary by Qodo

Uh oh!

qodo-code-review Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

HenrikHL commented Aug 20, 2026

Uh oh!

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

Uh oh!

HenrikHL commented Aug 20, 2026

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

HenrikHL commented Aug 20, 2026 •

edited by atlassian Bot

Loading

qodo-code-review Bot commented Aug 20, 2026 •

edited

Loading