EBL 3.0: SD-2232: Add 'ZZ' option to countryCode

[HenrikHL]

SD-2232: Make sure to include ZZ as countryCode in eBL, Issuance, Surrender (if needed) and PINT

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 SD-2232 - Partially compliant Compliant requirements: Include the 'ZZ' option for unknown countries in countryCode fields. Apply this across eBL, Issuance, Surrender (if needed), and PINT specifications. Standardize handling/wording in address fields documentation. Non-compliant requirements: Keep the update consistent with what was done for Booking. Requires further human verification: Verify phrasing and placement match the exact wording and guidance previously used in Booking to ensure consistency in tone and formatting.

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Consistency Verify the 'Note:' placement and spacing is uniform across all updated countryCode descriptions, including those with additional 'Condition:' paragraphs, to avoid rendering inconsistencies in generated docs. type: string pattern: ^[A-Z]{2}$ minLength: 2 maxLength: 2 description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) **Condition:** Mandatory to provide in case `UN Location Code` is not provided **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. example: NL UNLocationCode: type: string pattern: ^[A-Z]{2}[A-Z2-9]{3}$ minLength: 5 maxLength: 5 description: | The UN Location code specifying where the place is located. The pattern used must be - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) example: NLAMS PlaceOfFinalDelivery: type: object title: Place of Final Delivery description: | An object to capture `Place of Final Delivery` location specified as: Identification of the seaport, freight terminal or other place at which the goods are handed over from the `Ocean Transport Intermediary` (OTI) issuing the `House Bill of Lading` to the `Consignee`. **Condition:** Mandatory if different from `Place of Delivery` at the `Master Transport Document` level. **Condition:** The location can be specified either using `UN Location Code` and/or (`Location Name` together with `Country Code`), all three properties can be specified. example: locationName: Hamburg UNLocationCode: DEHAM properties: locationName: type: string pattern: ^\S(?:.*\S)?$ maxLength: 35 description: | The name of the location. **Condition:** Mandatory to provide in case `UN Location Code` is not provided example: Port of Amsterdam countryCode: type: string pattern: ^[A-Z]{2}$ minLength: 2 maxLength: 2 description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) **Condition:** Mandatory to provide in case `UN Location Code` is not provided **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. example: NL UNLocationCode: type: string pattern: ^[A-Z]{2}[A-Z2-9]{3}$ Documentation Formatting Ensure the pipe-style multiline description renders as intended with the added blank line before the 'Note:' so that it does not introduce unintended extra spacing in published OpenAPI docs. example: North Holland countryCode: type: string pattern: ^[A-Z]{2}$ minLength: 2 maxLength: 2 description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. example: NL required: - street - city - countryCode ############### # City Location ############### City: type: object title: City description: | An object for storing city, state/region and country related information properties: city: type: string pattern: ^\S(?:.*\S)?$ maxLength: 35 description: | The name of the city. example: Amsterdam stateRegion: type: string maxLength: 65 description: | The name of the state/region. example: North Holland countryCode: type: string pattern: ^[A-Z]{2}$ minLength: 2 maxLength: 2 description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. example: NL required: - city - countryCode

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Clarify validation for ZZ The schemas still enforce pattern ^[A-Z]{2}$ without explicitly stating ZZ is an allowed non-ISO code, which may confuse implementers and validators relying strictly on ISO 3166-1 alpha-2. Consider explicitly documenting that ZZ is an intentional exception to ISO 3166 (per ISO 3166-1 user-assigned codes) and, if applicable, adjusting enum/validation guidance so tooling and validation pipelines consistently accept ZZ. Examples: ebl/v3/EBL_v3.0.2.yaml [4237-4240] description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. ebl/v3/issuance/EBL_ISS_v3.0.2.yaml [524-527] description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. Solution Walkthrough: Before: description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](...) **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. After: description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](...). The code `ZZ` can be used for unknown countries, as it is a user-assigned code element under the ISO 3166-1 standard. Suggestion importance[1-10]: 7 __ Why: This is a valid and impactful suggestion that improves the clarity and correctness of the API documentation, preventing potential confusion for implementers, which is crucial for a specification file.	Medium
General	Standardize note formatting Ensure consistent punctuation and formatting across all inserted notes to avoid markdown rendering issues and accidental extra blank lines in generated docs. Remove the trailing blank line before the note and use plain text "Note:" consistently to match surrounding style. ebl/v3/issuance/EBL_ISS_v3.0.2.yaml [1189-1193] description: | - The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) - - **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + The 2 characters for the country code using ISO 3166-1 alpha-2. + Note: In case the `countryCode` is unknown it is possible to use the code `ZZ`. example: BR Apply / Chat Suggestion importance[1-10]: 3 __ Why: The suggestion offers a minor improvement by standardizing the formatting of the added note for better consistency and readability, although the current formatting is also valid.	Low
Update