EBL 3.0: SD-3226: Include OOG object by HenrikHL · Pull Request #641 · dcsaorg/DCSA-OpenAPI

HenrikHL · 2026-07-31T11:52:12Z

SD-3226: Include OOG object

qodo-code-review · 2026-07-31T11:53:12Z

PR Summary by Qodo

EBL 3.0: Add OutOfGaugeDetails object and OOG quote reference fields

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Add Out of Gauge (OOG) details object to requested equipment payloads.
• Define OOG dimension/extension/center-of-gravity schemas for consistent OOG modeling.
• Add OOG feasibility/commercial quote reference field alongside quotation references.

Diagram

graph TD
  A["ebl/v3/EBL_v3.0.4.yaml"] --> D(["OutOfGaugeDetails schema"]) --> E(["Supporting schemas: Dimensions/Extensions/COG/Measurement"])
  B["ebl/v3/issuance/EBL_ISS_v3.0.4.yaml"] --> D
  C["pint/v3/EBL_PINT_v3.0.0.yaml"] --> D
  A --> F(["outOfGaugeQuoteReference field"])
  B --> F
  C --> F

High-Level Assessment

The following are alternative approaches to this PR:

1. Reuse an existing shared Measurement schema (if already defined elsewhere)

➕ Avoids duplicated schema names across the spec
➕ Improves consistency for all dimensional fields (not just OOG)
➕ Reduces maintenance when units/classifiers evolve
➖ May require refactoring existing references/locations to a common component
➖ Potentially a breaking change if prior Measurement differs semantically

2. Model CenterOfGravity.referencePoint as an enum (not free string)

➕ Stronger validation for producers/consumers
➕ Clearer contract for allowed reference points
➕ Better codegen support in strongly typed clients
➖ Some generators/tooling handle long enums less ergonomically
➖ Future additions require spec change (though that may be desirable)

Recommendation: The overall approach (add OutOfGaugeDetails + supporting schemas and reference them from equipment) is appropriate for a contract-first API. Before merging, verify whether a Measurement schema already exists in these specs to prevent accidental duplication/name clashes, and consider upgrading CenterOfGravity.referencePoint to an explicit enum to improve interoperability and validation.

Files changed (3) +699 / -0

Enhancement (3) +699 / -0

EBL_v3.0.4.yamlAdd OutOfGaugeDetails schemas and reference from equipment +233/-0

Add OutOfGaugeDetails schemas and reference from equipment

• Introduces an outOfGaugeDetails reference on the requested equipment schema and defines OutOfGaugeDetails plus supporting schemas (TotalCargoDimensions, OutOfGaugeExtensions, CenterOfGravity, Measurement). Also adds outOfGaugeQuoteReference alongside existing quotation reference fields.

ebl/v3/EBL_v3.0.4.yaml

EBL_ISS_v3.0.4.yamlMirror OOG details and OOG quote reference in issuance spec +233/-0

Mirror OOG details and OOG quote reference in issuance spec

• Adds outOfGaugeQuoteReference to the commercial/quotation reference area and adds outOfGaugeDetails to requested equipment. Includes the same OOG schema definitions as the main EBL spec for issuance payload parity.

ebl/v3/issuance/EBL_ISS_v3.0.4.yaml

EBL_PINT_v3.0.0.yamlMirror OOG details and OOG quote reference in PINT spec +233/-0

Mirror OOG details and OOG quote reference in PINT spec

• Adds outOfGaugeQuoteReference and introduces outOfGaugeDetails on requested equipment. Defines the OOG schema set (dimensions/extensions/CoG/measurement) to keep PINT aligned with EBL 3.0 OOG modeling.

pint/v3/EBL_PINT_v3.0.0.yaml

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

qodo-code-review · 2026-07-31T11:54:43Z

Code Review by Qodo

🐞 Bugs (2) 📘 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. OOG frame mismatch 🐞 Bug ≡ Correctness ⭐ New

Description

TotalCargoDimensions is described in cargo-relative axes (cargo longitudinal/vertical axis) while
OutOfGaugeExtensions is defined relative to the equipment envelope (front/rear/left/right of the
equipment unit), but the spec does not define how these frames relate when cargo is not perfectly
aligned with the equipment. This ambiguity can cause different implementers to report incompatible
OOG values for the same physical shipment (especially for rotated/asymmetrically placed cargo).

Code

ebl/v3/EBL_v3.0.4.yaml[R9528-9559]

+        Overall external dimensions of the cargo in its final packed and secured transport condition.
+      properties:
+        length:
+          type: object
+          title: Length
+          description: |
+            Overall length of the cargo, measured along its longitudinal axis.
+          allOf:
+            - $ref: '#/components/schemas/Measurement'
+        width:
+          type: object
+          title: Width
+          description: |
+            Overall width of the cargo, measured horizontally, perpendicular to its declared longitudinal axis.
+          allOf:
+            - $ref: '#/components/schemas/Measurement'
+        height:
+          type: object
+          title: Height
+          description: |
+            Overall height of the cargo, measured vertically along its vertical axis, from its lowest to highest point.
+          allOf:
+            - $ref: '#/components/schemas/Measurement'
+
+    #########################
+    # Out of Gauge Extensions
+    #########################
+    OutOfGaugeExtensions:
+      type: object
+      title: Out of Gauge Extensions
+      description: |
+        Directional measurements describing how far the cargo extends beyond the standard equipment envelope. Each value represents only the excess portion, not the total dimension. For equipment with doors, the front is the end opposite the doors and the rear is the door end. Left and right are determined when looking from the rear toward the front. For equipment without doors, use the orientation defined by the equipment provider.

Evidence

In the updated OOG schemas, TotalCargoDimensions is defined using cargo-centric axis language, while
OutOfGaugeExtensions is explicitly defined relative to the equipment unit and its envelope; without
a stated mapping/alignment constraint, these two sets of measurements can’t be consistently related
for rotated or otherwise non-aligned cargo. The same pattern appears in all four updated spec files.

ebl/v3/EBL_v3.0.4.yaml[9528-9593]
bkg/v2/BKG_v2.0.5.yaml[6895-6960]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[2591-2656]
pint/v3/EBL_PINT_v3.0.0.yaml[3249-3314]

Agent prompt

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

## Issue description
`TotalCargoDimensions` is currently described using the cargo’s own axes (e.g., “measured along its longitudinal axis”), while `OutOfGaugeExtensions` is explicitly defined relative to the equipment unit (equipment envelope, equipment front/rear/left/right). The spec does not state how the cargo axes map to the equipment axes (or whether cargo must be aligned), which makes the data ambiguous for non-aligned cargo.

## Issue Context
This wording is duplicated across multiple API specs (BKG/EBL/EBL issuance/PINT). The simplest resolution is either:
1) Define `TotalCargoDimensions` in the equipment-unit coordinate system (parallel/perpendicular to the equipment longitudinal axis; height from equipment base), OR
2) Keep cargo-centric wording but explicitly require/define cargo-to-equipment alignment (e.g., cargo longitudinal axis MUST be parallel to equipment longitudinal axis; no rotation permitted) or add an explicit orientation/rotation field.

## Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[6895-6960]
- ebl/v3/EBL_v3.0.4.yaml[9528-9593]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[2591-2656]
- pint/v3/EBL_PINT_v3.0.0.yaml[3249-3314]

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

2. OOG quote allows blanks 🐞 Bug ≡ Correctness

Description

The newly added outOfGaugeQuoteReference field lacks the non-blank/trim pattern used by the other
quotation reference fields, so empty strings or whitespace-only values will pass schema validation
where a real reference appears intended.

Code

ebl/v3/EBL_v3.0.4.yaml[R10255-10260]

+        outOfGaugeQuoteReference:
+          type: string
+          maxLength: 70
+          description: |
+            Reference number of the OOG feasibility assessment or commercial quote previously issued by the carrier for this shipment.
+          example: OOG-QUOTE-2026-000123

Evidence
In all three specs, adjacent quotation reference fields enforce pattern: ^\S(?:.*\S)?$ while the
new outOfGaugeQuoteReference does not, which makes empty/whitespace-only strings valid under the
schema.
ebl/v3/EBL_v3.0.4.yaml[10236-10260]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1006-1030]
pint/v3/EBL_PINT_v3.0.0.yaml[1666-1689]

Agent prompt

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

### Issue description
`outOfGaugeQuoteReference` is defined without a `pattern` (and without `minLength`), unlike the neighboring `contractQuotationReference` / `extendedContractQuotationReference` fields which enforce `^\S(?:.*\S)?$`. This means `""` and values like `"   "` are considered valid by the schema.

### Issue Context
This field is added in three API specs (EBL, EBL issuance, and PINT). To keep validation consistent and avoid accepting blank references, apply the same `pattern: ^\S(?:.*\S)?$` used by the other reference fields (and optionally consider `minLength: 1` if that is a project standard).

### Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[10255-10260]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1025-1030]
- pint/v3/EBL_PINT_v3.0.0.yaml[1684-1689]

ⓘ 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.}

Previous review results

Review updated until commit 097367d ⚖️ Balanced

Results up to commit c57c765 ⚖️ Balanced

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

1. OOG quote allows blanks 🐞 Bug ≡ Correctness

Description

The newly added outOfGaugeQuoteReference field lacks the non-blank/trim pattern used by the other
quotation reference fields, so empty strings or whitespace-only values will pass schema validation
where a real reference appears intended.

Code

ebl/v3/EBL_v3.0.4.yaml[R10255-10260]

+        outOfGaugeQuoteReference:
+          type: string
+          maxLength: 70
+          description: |
+            Reference number of the OOG feasibility assessment or commercial quote previously issued by the carrier for this shipment.
+          example: OOG-QUOTE-2026-000123

Evidence
In all three specs, adjacent quotation reference fields enforce pattern: ^\S(?:.*\S)?$ while the
new outOfGaugeQuoteReference does not, which makes empty/whitespace-only strings valid under the
schema.
ebl/v3/EBL_v3.0.4.yaml[10236-10260]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1006-1030]
pint/v3/EBL_PINT_v3.0.0.yaml[1666-1689]

Agent prompt

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

### Issue description
`outOfGaugeQuoteReference` is defined without a `pattern` (and without `minLength`), unlike the neighboring `contractQuotationReference` / `extendedContractQuotationReference` fields which enforce `^\S(?:.*\S)?$`. This means `""` and values like `"   "` are considered valid by the schema.

### Issue Context
This field is added in three API specs (EBL, EBL issuance, and PINT). To keep validation consistent and avoid accepting blank references, apply the same `pattern: ^\S(?:.*\S)?$` used by the other reference fields (and optionally consider `minLength: 1` if that is a project standard).

### Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[10255-10260]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[1025-1030]
- pint/v3/EBL_PINT_v3.0.0.yaml[1684-1689]

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

Results up to commit 5498ffd ⚖️ Balanced

No changes from previous review

HenrikHL · 2026-07-31T13:13:48Z

/agentic_review

qodo-code-review · 2026-07-31T13:18:16Z

Code review by qodo was updated up to the latest commit 5498ffd

HenrikHL · 2026-07-31T16:46:33Z

/agentic_review

qodo-code-review · 2026-07-31T16:52:08Z

Code review by qodo was updated up to the latest commit 097367d

HenrikHL · 2026-08-03T11:26:50Z

/agentic_review

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Suppressed comments (5)

bkg/v2/BKG_v2.0.5.yaml:3379

outOfGaugeQuotationReference is a new field name in this schema; if it replaces the previously documented outOfGaugeQuoteReference (as indicated by the diff), that is a breaking change for consumers targeting BKG v2.0.5. Consider keeping outOfGaugeQuoteReference as a deprecated alias (or publishing this change under a new API/spec version) to preserve backwards compatibility.

        outOfGaugeQuotationReference:
          type: string
          maxLength: 70
          description: |
            Reference number of the Out of Gauge feasibility assessment or commercial quote previously issued by the carrier for this shipment.

bkg/v2/BKG_v2.0.5.yaml:3856

outOfGaugeQuotationReference is a new field name in this schema; if it replaces the previously documented outOfGaugeQuoteReference (as indicated by the diff), that is a breaking change for consumers targeting BKG v2.0.5. Consider keeping outOfGaugeQuoteReference as a deprecated alias (or publishing this change under a new API/spec version) to preserve backwards compatibility.

        outOfGaugeQuotationReference:
          type: string
          maxLength: 70
          description: |
            Reference number of the Out of Gauge feasibility assessment or commercial quote previously issued by the carrier for this shipment.

pint/v3/EBL_PINT_v3.0.0.yaml:1689

For consistency with contractQuotationReference / extendedContractQuotationReference in this same schema, consider adding the ^\S(?:.*\S)?$ pattern to outOfGaugeQuotationReference to prevent leading/trailing whitespace.

        outOfGaugeQuotationReference:
          type: string
          maxLength: 70
          description: |
            Reference number of the Out of Gauge feasibility assessment or commercial quote previously issued by the carrier for this shipment.

ebl/v3/issuance/EBL_ISS_v3.0.4.yaml:1030

For consistency with contractQuotationReference / extendedContractQuotationReference in this same schema, consider adding the ^\S(?:.*\S)?$ pattern to outOfGaugeQuotationReference to prevent leading/trailing whitespace.

        outOfGaugeQuotationReference:
          type: string
          maxLength: 70
          description: |
            Reference number of the Out of Gauge feasibility assessment or commercial quote previously issued by the carrier for this shipment.

ebl/v3/EBL_v3.0.4.yaml:10262

For consistency with contractQuotationReference / extendedContractQuotationReference in this same schema, consider adding the ^\S(?:.*\S)?$ pattern to outOfGaugeQuotationReference to prevent leading/trailing whitespace.

        outOfGaugeQuotationReference:
          type: string
          maxLength: 70
          description: |
            Reference number of the Out of Gauge feasibility assessment or commercial quote previously issued by the carrier for this shipment.

EBL 3.0: SD-3226: Include OOG object

c57c765

HenrikHL requested a review from Copilot July 31, 2026 11:52

Copilot started reviewing on behalf of HenrikHL July 31, 2026 11:53 View session

Copilot AI reviewed Jul 31, 2026

qodo-code-review Bot reviewed Jul 31, 2026

View reviewed changes

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

HenrikHL added 3 commits July 31, 2026 14:23

Rename outOfGaugeQuoteReference -> outOfGaugeQuotationReference

b15b357

Add outOfGaugeDetails to SI

f7b6cfb

Change "OOG" -> "Out of Gauge"

5498ffd

Update descriptions

097367d

qodo-code-review Bot reviewed Jul 31, 2026

View reviewed changes

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

Improve descriptions

d91e819

HenrikHL requested a review from Copilot August 3, 2026 11:26

Copilot started reviewing on behalf of HenrikHL August 3, 2026 11:27 View session

Copilot AI reviewed Aug 3, 2026

View reviewed changes

Comment thread bkg/v2/BKG_v2.0.5.yaml

HenrikHL merged commit 6448edd into master Aug 4, 2026
2 checks passed

HenrikHL deleted the SD-3226_Include-OOG-object branch August 4, 2026 08:44

Navigation Menu

Uh oh!

EBL 3.0: SD-3226: Include OOG object - #641

EBL 3.0: SD-3226: Include OOG object#641
HenrikHL merged 6 commits into
masterfrom
SD-3226_Include-OOG-object

HenrikHL commented Jul 31, 2026 •

edited by atlassian Bot

Loading

Uh oh!

qodo-code-review Bot commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

qodo-code-review Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

Uh oh!

HenrikHL commented Jul 31, 2026

Uh oh!

qodo-code-review Bot commented Jul 31, 2026

Uh oh!

HenrikHL commented Jul 31, 2026

Uh oh!

Uh oh!

qodo-code-review Bot commented Jul 31, 2026

Uh oh!

HenrikHL commented Aug 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

HenrikHL commented Jul 31, 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 Jul 31, 2026

PR Summary by Qodo

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Code Review by Qodo

Previous review results

Uh oh!

Uh oh!

HenrikHL commented Jul 31, 2026

Uh oh!

qodo-code-review Bot commented Jul 31, 2026

Uh oh!

HenrikHL commented Jul 31, 2026

Uh oh!

Uh oh!

qodo-code-review Bot commented Jul 31, 2026

Uh oh!

HenrikHL commented Aug 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

HenrikHL commented Jul 31, 2026 •

edited by atlassian Bot

Loading

qodo-code-review Bot commented Jul 31, 2026 •

edited

Loading