EBL 3.0: SD-3102: Add NA to codeListProvider for Consignee and Endorsee

[HenrikHL]

SD-3102: Add NA as codeListProvider when no IdentifyingCode is available or exists for a Party

[qodo-code-review]

PR Summary by Qodo

EBL 3.0: Allow NA codeListProvider for Consignee/Endorsee identifying codes

✨ Enhancement 📝 Documentation 🕐 10-20 Minutes

AI Description

• Add NA as an allowed codeListProvider when no identifying code exists.
• Introduce IdentifyingCodeExtended schema documenting NA/NO VALUE conditions.
• Update EBL, issuance, and PINT specs to reference the extended schema.

Diagram

graph TD
  A["EBL API spec"] --> D["IdentifyingCodeExtended"]
  B["Issuance API spec"] --> D
  C["PINT API spec"] --> D
  D --> E["codeListProvider=NA rule"] --> F["partyCode=NO VALUE rule"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Modify existing IdentifyingCode schema in-place

• ➕ Single schema to maintain; avoids duplicating schema definitions
• ➕ All uses automatically gain the NA option
• ➖ Broad behavioral change across all party roles/contexts (higher compatibility risk)
• ➖ Harder to scope the NA semantics only to Consignee/Endorsee as requested

2. Use oneOf to extend IdentifyingCode (e.g., IdentifyingCode | IdentifyingCodeWithNA)

• ➕ Expresses extension without duplicating the full schema
• ➕ Allows scoping the NA-capable variant to specific fields
• ➖ More complex OpenAPI constructs for generators/validators
• ➖ May reduce readability compared to a single explicit schema

Recommendation: Keep the current approach (introducing IdentifyingCodeExtended and updating only the relevant identifyingCodes arrays) because it scopes the NA allowance to the intended party roles while minimizing unintended downstream impacts. Consider oneOf only if schema duplication becomes a maintenance burden across versions.

Files changed (3) +201 / -6

Enhancement (3) +201 / -6

EBL_v3.0.4.yamlReference IdentifyingCodeExtended for selected party identifyingCodes +67/-2

Reference IdentifyingCodeExtended for selected party identifyingCodes

• Switches specific 'identifyingCodes.items' references from 'IdentifyingCode' to 'IdentifyingCodeExtended'. Adds the 'IdentifyingCodeExtended' schema including 'NA' as a documented option and the associated 'partyCode' condition.

ebl/v3/EBL_v3.0.4.yaml

EBL_ISS_v3.0.4.yamlAdd IdentifyingCodeExtended and update issuance party identifyingCodes to use it +67/-2

Add IdentifyingCodeExtended and update issuance party identifyingCodes to use it

• Introduces 'IdentifyingCodeExtended' to the issuance API components and updates the relevant party 'identifyingCodes' arrays to reference it. Documents 'NA' usage and the required 'NO VALUE' partyCode behavior when 'NA' is used.

ebl/v3/issuance/EBL_ISS_v3.0.4.yaml

EBL_PINT_v3.0.0.yamlAdd IdentifyingCodeExtended and update PINT party identifyingCodes to use it +67/-2

Add IdentifyingCodeExtended and update PINT party identifyingCodes to use it

• Adds the 'IdentifyingCodeExtended' schema to the PINT spec and updates the applicable party 'identifyingCodes.items' references to point to it. Captures the 'NA' provider option and the conditional requirement for 'partyCode'.

pint/v3/EBL_PINT_v3.0.0.yaml

[qodo-code-review]

Code Review by Qodo

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

Context used

✅ Tickets: SD-3102

1. Inconsistent NA condition ✓ Resolved 🐞 Bug ≡ Correctness

Description

IdentifyingCodeExtended’s description says to use NA when codeListProvider “does not exist”, but
codeListProvider is required by the same schema, making the normative rule internally
inconsistent. The same block also contains a typo (“Condtion”) in a MUST statement, replicated
across the three specs.

Code

ebl/v3/EBL_v3.0.4.yaml[R7709-7717]

+            **Condition:** When `codeListProvider` does not exist or is not applicable then `NA` MUST be used.
+          example: W3C
+        partyCode:
+          type: string
+          maxLength: 150
+          description: |
+            Code to identify the party as provided by the `codeListProvider`.
+
+            **Condtion:** when `codeListProvider='NA'` the corresponding `partyCode` MUST be set to `NO VALUE`.

Evidence

The schema requires codeListProvider, yet its own description discusses the case where
codeListProvider does not exist, which cannot occur under the schema as written; the same typo and
wording appear in issuance and PINT copies.

ebl/v3/EBL_v3.0.4.yaml[7668-7731]
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[741-794]
pint/v3/EBL_PINT_v3.0.0.yaml[1461-1496]

Agent prompt

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

## Issue description
`IdentifyingCodeExtended` introduces normative wording that is internally inconsistent: it states that when `codeListProvider` does not exist then `NA` must be used, while the schema simultaneously requires `codeListProvider`. This should be reworded to describe the intended scenario (e.g., when no identifying code/provider is applicable, set `codeListProvider` to `NA`), and fix the typo `Condtion` -> `Condition`.

## Issue Context
The current text is likely meant to define how to populate the required `identifyingCodes` entry for Consignee/Endorsee when no real identifier is available.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[7709-7718]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[772-781]
- pint/v3/EBL_PINT_v3.0.0.yaml[1474-1483]

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

---

2. Duplicate IdentifyingCode schemas ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The PR introduces IdentifyingCodeExtended with the same structure as IdentifyingCode and
repoints Consignee/Endorsee to it, creating two parallel schema types for the same object shape.
This duplication increases drift risk (future edits must be applied twice) and needlessly fragments
schema/type usage across the specs.

Code

ebl/v3/EBL_v3.0.4.yaml[R6198-6201]

          type: array
          minItems: 1
          items:
-            $ref: '#/components/schemas/IdentifyingCode'
+            $ref: '#/components/schemas/IdentifyingCodeExtended'

Evidence

Consignee/Endorsee now reference IdentifyingCodeExtended, while both IdentifyingCode and
IdentifyingCodeExtended are defined in the same file with the same structural fields and required
list, demonstrating duplication and type fragmentation.

ebl/v3/EBL_v3.0.4.yaml[6197-6202]
ebl/v3/EBL_v3.0.4.yaml[6566-6571]
ebl/v3/EBL_v3.0.4.yaml[7609-7731]

Agent prompt

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

## Issue description
`IdentifyingCodeExtended` duplicates `IdentifyingCode` (same properties + required list) and is only used to change descriptive/normative text about `NA`. This creates a maintenance hazard and inconsistent type usage.

## Issue Context
`Consignee.identifyingCodes` and `Endorsee.identifyingCodes` were switched to `$ref: IdentifyingCodeExtended`, while many other places still use `IdentifyingCode`. If the intent is simply to allow/document `NA`, prefer updating the existing `IdentifyingCode` schema (and keep refs unchanged), or otherwise factor the shared structure to prevent divergence.

## Fix Focus Areas
- ebl/v3/EBL_v3.0.4.yaml[6197-6202]
- ebl/v3/EBL_v3.0.4.yaml[6566-6571]
- ebl/v3/EBL_v3.0.4.yaml[7609-7731]
- ebl/v3/issuance/EBL_ISS_v3.0.4.yaml[3564-3570]
- pint/v3/EBL_PINT_v3.0.0.yaml[4258-4263]

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

---

[Copilot]

Pull request overview

This PR updates the EBL 3.0 OpenAPI specifications to allow a “Not Applicable” identifying-code provider (NA) for parties that must still provide an identifyingCodes entry even when no real identifying code exists (per SD-3102).

Changes:

• Added a new IdentifyingCodeExtended schema (including NA in the documented provider list + NA-specific conditions).
• Updated Consignee.identifyingCodes and Endorsee.identifyingCodes item schema references to IdentifyingCodeExtended.
• Applied the above updates consistently across the PINT, Issuance, and main EBL v3 specs.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 6 comments.

File	Description
pint/v3/EBL_PINT_v3.0.0.yaml	Adds IdentifyingCodeExtended and switches Consignee/Endorsee identifyingCodes to it.
ebl/v3/issuance/EBL_ISS_v3.0.4.yaml	Adds IdentifyingCodeExtended and switches Consignee/Endorsee identifyingCodes to it.
ebl/v3/EBL_v3.0.4.yaml	Adds IdentifyingCodeExtended and switches Consignee/Endorsee identifyingCodes to it.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 9 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

ebl/v3/surrender/EBL_SUR_v3.0.4.yaml:511

• The IdentifyingCode.partyCode description doesn’t document how partyCode should be populated for the No Party placeholder, even though the schema now explicitly allows codeListProvider='NONE' and the earlier example sets partyCode to NONE. Adding the corresponding condition here would make the placeholder requirements self-contained and consistent.

        partyCode:
          type: string
          description: |
            Code to identify the party as provided by the `codeListProvider`
          maxLength: 150