BKG 2.0, EBL 3.0: SD-3105, SD-3226: Update OOG according to review comments

[HenrikHL]

SD-3105: Update OOG in BKG according to review comments in this Jira Issue
SD-3226: Update OOG in SI/TD + ISS and PINT according to review comments in this Jira Issue

[qodo-code-review]

PR Summary by Qodo

Clarify and refine Out-of-Gauge (OOG) schemas across BKG 2.0 and EBL 3.0

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Clarify OOG dimension/extension semantics and enforce positive-value guidance.
• Replace CoG single referencePoint with axis-specific reference points and clearer offset meaning.
• Document requestedEquipment rules for multiple units sharing identical OOG details.

Diagram

graph TD
  C{{"API consumers"}} --> B["bkg/v2/BKG_v2.0.5.yaml"] --> O1(["OOG + CoG schemas"])
  C --> E["ebl/v3/EBL_v3.0.4.yaml"] --> O2(["OOG + CoG schemas"])
  C --> I["ebl/v3/issuance/EBL_ISS_v3.0.4.yaml"] --> O3(["OOG + CoG schemas"])
  C --> P["pint/v3/EBL_PINT_v3.0.0.yaml"] --> O4(["OOG + CoG schemas"])
  subgraph Legend
    direction LR
    _ext{{"External"}} ~~~ _file["Spec file"] ~~~ _schema(["Schema group"])
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Extract shared OOG schemas into a common component library

• ➕ Prevents drift across BKG/EBL/ISS/PINT specs
• ➕ Reduces repeated review effort for future OOG changes
• ➕ Encourages consistent wording and constraints
• ➖ May require toolchain support for cross-file $ref resolution/publishing
• ➖ Could complicate versioning when specs need to diverge

2. Keep single CoG referencePoint but constrain via enum + axis fields

• ➕ More backwards compatible for clients already using referencePoint
• ➕ Avoids introducing 3 new properties and new required-if-present rules
• ➖ Retains ambiguity and verbosity from the combined 3D reference-point list
• ➖ Harder to explain sign conventions per axis without splitting semantics

Recommendation: Given the review comments’ intent to make CoG semantics clearer, the split into longitudinal/transverse/vertical reference points is reasonable and improves interpretability. If these YAMLs are expected to evolve together long-term, consider a shared schema extraction in a follow-up to reduce duplication and keep OOG definitions aligned.

Files changed (4) +126 / -154

Enhancement (4) +126 / -154

BKG_v2.0.5.yamlClarify RequestedEquipment OOG rules and refine OOG/CoG schemas +36/-40

Clarify RequestedEquipment OOG rules and refine OOG/CoG schemas

• Updates RequestedEquipment text to reference ISOEquipmentCode and clarifies how outOfGaugeDetails apply when units > 1. Refines Total Cargo Dimensions and Out of Gauge Extensions descriptions to require positive values and omit non-applicable directions. Replaces the single CoG referencePoint with axis-specific reference points and clearer offset sign conventions.

bkg/v2/BKG_v2.0.5.yaml

EBL_v3.0.4.yamlRefine OOG dimensions/extensions wording and split CoG reference points +30/-38

Refine OOG dimensions/extensions wording and split CoG reference points

• Clarifies Total Cargo Dimensions and Out of Gauge Extensions semantics, including positive-value guidance and omission rules for non-extended directions. Replaces CoG referencePoint with longitudinal/transverse/vertical reference points and defines offset sign meaning relative to each reference.

ebl/v3/EBL_v3.0.4.yaml

EBL_ISS_v3.0.4.yamlAlign Issuance spec OOG/CoG semantics with EBL updates +30/-38

Align Issuance spec OOG/CoG semantics with EBL updates

• Updates Total Cargo Dimensions and Out of Gauge Extensions descriptions to clarify required positivity and omission behavior. Splits the CoG referencePoint into axis-specific reference points with explicit sign conventions for offsets.

ebl/v3/issuance/EBL_ISS_v3.0.4.yaml

EBL_PINT_v3.0.0.yamlAlign PINT spec OOG/CoG semantics with EBL updates +30/-38

Align PINT spec OOG/CoG semantics with EBL updates

• Updates Total Cargo Dimensions and Out of Gauge Extensions descriptions to clarify required positivity and omission behavior. Splits the CoG referencePoint into axis-specific reference points with explicit sign conventions for offsets.

pint/v3/EBL_PINT_v3.0.0.yaml

[qodo-code-review]

Code Review by Qodo

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

1. OOG positivity not enforced 🐞 Bug ≡ Correctness

Description

The specs now state that TotalCargoDimensions and OutOfGaugeExtensions values must be greater than
zero (and extensions must be omitted if no extension), but those fields still $ref Measurement which
allows any number (including 0/negative). This creates a contract mismatch where schema-based
validation/SDKs will accept values the text explicitly forbids.

Code

bkg/v2/BKG_v2.0.5.yaml[R6998-7000]

      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.
+        Directional measurements describing how far the cargo extends beyond the standard equipment envelope. Each value represents only the excess portion, not the total dimension. Each provided extension value must be greater than zero. If the cargo does not extend beyond the equipment boundary in a particular direction, the corresponding property must be omitted. 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.
      properties:

Evidence

The updated descriptions introduce strict "> 0" and omission rules, but the referenced Measurement
schema does not constrain numeric ranges; the file already demonstrates use of `exclusiveMinimum:
true` in other schemas, so this is an enforceable omission rather than a tooling limitation.

bkg/v2/BKG_v2.0.5.yaml[6964-6990]
bkg/v2/BKG_v2.0.5.yaml[6992-7035]
bkg/v2/BKG_v2.0.5.yaml[7099-7129]
bkg/v2/BKG_v2.0.5.yaml[5580-5608]
ebl/v3/EBL_v3.0.4.yaml[9544-9615]

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 OOG prose requirements ("must be greater than zero" and "omit property if no extension") are not represented in the OpenAPI schema. Because these fields reference `#/components/schemas/Measurement` (which has no minimum constraint), schema-based tooling will allow 0/negative values and explicitly-present 0-valued extensions.

### Issue Context
You cannot add a global `minimum > 0` to `Measurement` because it is also used for offsets (which explicitly allow negative values). Instead, introduce a dedicated positive-only measurement schema (or override `value` via `allOf`) for dimensions/extensions.

### Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[6964-7035]
- bkg/v2/BKG_v2.0.5.yaml[7099-7129]
- ebl/v3/EBL_v3.0.4.yaml[9544-9615]
- ebl/v3/EBL_v3.0.4.yaml[9678-9712]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[2599-2636]
- pint/v3/EBL_PINT_v3.0.0.yaml[3257-3294]

### Suggested implementation approach
1. Add a new schema, e.g. `PositiveMeasurement`, using `allOf` with `Measurement` plus a constraint on `properties.value`:
  - `minimum: 0`
  - `exclusiveMinimum: true`
2. Replace `allOf: [ $ref: '#/components/schemas/Measurement' ]` with `allOf: [ $ref: '#/components/schemas/PositiveMeasurement' ]` for:
  - `TotalCargoDimensions.length/width/height`
  - `OutOfGaugeExtensions.*`
3. Apply consistently in BKG + EBL + ISS + PINT to avoid spec divergence.

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

---

2. COG referencepoints unconstrained 🐞 Bug ≡ Correctness

Description

CenterOfGravity now says each *ReferencePoint is required when the corresponding *Offset is
provided, but the schema has no way to enforce that dependency and also does not restrict the
reference point values to the listed set (no enum). This allows invalid/ambiguous CenterOfGravity
objects to pass schema validation and into downstream implementations.

Code

bkg/v2/BKG_v2.0.5.yaml[R7050-7054]

+            Longitudinal reference point from which longitudinalOffset is measured. Required if longitudinalOffset is provided. Possible values:
+              - `FRONT` (Front)
+              - `CENTER` (Center)
+              - `REAR` (Rear)
+          example: FRONT

Evidence

The schema explicitly documents allowed values and conditional requirements in the descriptions, but
the properties are unconstrained strings and the object has no required/pairing mechanism; other
parts of the spec use enum (e.g., units), demonstrating this is intended to be machine-enforced
when values are fixed.

bkg/v2/BKG_v2.0.5.yaml[7040-7087]
ebl/v3/EBL_v3.0.4.yaml[9620-9667]
bkg/v2/BKG_v2.0.5.yaml[5588-5605]

Agent prompt

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

### Issue description
`CenterOfGravity` introduces new fields (`longitudinalReferencePoint`, `transverseReferencePoint`, `verticalReferencePoint`) with prose-defined allowed values and conditional-required semantics, but:
- The reference point fields are plain strings without `enum`.
- The schema does not enforce "referencePoint required if offset present", so invalid partial objects can validate.

### Issue Context
This is repeated across BKG, EBL, ISS, and PINT. While OpenAPI 3.0 lacks full JSON Schema dependencies, you can still improve correctness by (a) adding `enum`s and (b) restructuring to make paired fields validate together.

### Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[7040-7093]
- ebl/v3/EBL_v3.0.4.yaml[9620-9673]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[2674-2727]
- pint/v3/EBL_PINT_v3.0.0.yaml[3332-3385]

### Suggested implementation approach
1. Add `enum` to each reference point property to match the documented values.
2. Prefer modeling each axis as an optional object with required internal fields, e.g.:
  - `longitudinal: { referencePoint, offset }` with `required: [referencePoint, offset]`
  This ensures schema validation cannot accept an offset without its reference.
3. If restructuring is too breaking, at minimum add `enum`s now; that still prevents arbitrary strings.

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

---

Context sources

✅ Tickets: 🎫 BKG 2.0.5 API: Include OOG object 🎫 eBL 3.0.4 API (SI, TD): Include OOG object

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 ↗