BKG 2.0, EBL 3.0: SD-2703: Add addressLines and align conditions

bkg/v2/BKG_v2.0.4.yaml

@@ -4495,6 +4495,17 @@ components:
           example: IKEA Denmark
         address:
           $ref: '#/components/schemas/PartyAddress'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         partyContactDetails:
           type: array
           minItems: 1
@@ -4537,6 +4548,17 @@ components:
           example: IKEA Denmark
         address:
           $ref: '#/components/schemas/PartyAddress'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         partyContactDetails:
           type: array
           minItems: 1
@@ -4590,6 +4612,17 @@ components:
           example: IKEA Denmark
         address:
           $ref: '#/components/schemas/PartyAddress'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         partyContactDetails:
           type: array
           minItems: 1
@@ -4643,6 +4676,17 @@ components:
           example: IKEA Denmark
         address:
           $ref: '#/components/schemas/PartyAddress'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         partyContactDetails:
           type: array
           minItems: 1
@@ -4698,6 +4742,17 @@ components:
           example: NLAMS
         address:
           $ref: '#/components/schemas/Address'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         partyContactDetails:
           type: array
           minItems: 1
@@ -4777,6 +4832,17 @@ components:
           example: IKEA Denmark
         address:
           $ref: '#/components/schemas/PartyAddress'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         identifyingCodes:
           type: array
           items:
@@ -5158,12 +5224,15 @@ components:
       title: Location
       description: |
         The location can be specified using **any** of the nested structures:
-        - `address` (used to specify the location via an Address)
+        - `address` (used to specify the location via a **structured** Address)
+        - `addressLines` (used to specify a location via an **unstructured** Address)
         - `UNLocationCode`
         - `facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`)
         - `geoCoordinate` (used to specify a location using `latitude` and `longitude`)
 
         **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location.
+
+        **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
       example:
         locationName: CMP Container Terminal Copenhagen
         UNLocationCode: DKCPH
@@ -5184,6 +5253,19 @@ components:
           example: Building 123
         address:
           $ref: '#/components/schemas/Address'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+
+            **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         facility:
           $ref: '#/components/schemas/Facility'
         UNLocationCode:
@@ -5468,9 +5550,11 @@ components:
 
         **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`).
 
-        The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`.
+        The location can be specified in **any** of the following ways: `Address` (structured address), `AddressLines` (unstructured address), `Facility`, `UN Location Code` or a `GeoCoordinate`.
 
         **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location.
+
+        **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
       example:
         locationName: Shanghai Shengdong International Container Terminal
         UNLocationCode: CNSGH
@@ -5491,6 +5575,19 @@ components:
           example: Building 123
         address:
           $ref: '#/components/schemas/Address'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+
+            **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         facility:
           $ref: '#/components/schemas/Facility'
         UNLocationCode:
@@ -5517,9 +5614,11 @@ components:
 
         The location of the depot from which the empty container(s) will be released from
 
-        The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`.
+        The location can be specified in **any** of the following ways: `Address` (structured address), `AddressLines` (unstructured address), `Facility`, `UN Location Code` or a `GeoCoordinate`.
 
         **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location.
+
+        **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
       example:
         locationName: Shanghai Shengdong International Container Terminal
         UNLocationCode: CNSGH
@@ -5540,6 +5639,19 @@ components:
           example: Building 123
         address:
           $ref: '#/components/schemas/Address'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+
+            **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         facility:
           $ref: '#/components/schemas/Facility'
         UNLocationCode:
@@ -6444,15 +6556,15 @@ components:
       type: object
       title: Net Explosive Content
       description: |
-        The total weight of the explosive substances, without the packaging’s, casings, etc.
+        The total weight of the explosive substances, without the packaging's, casings, etc.
       properties:
         value:
           type: number
           format: float
           minimum: 0
           exclusiveMinimum: true
           description: |
-            The total weight of the explosive substances, without the packaging’s, casings, etc.
+            The total weight of the explosive substances, without the packaging's, casings, etc.
           example: 2.4
         unit:
           type: string
@@ -6830,15 +6942,18 @@ components:
         - dischargeLocation
         - plannedDepartureDate
         - plannedArrivalDate
+
     LoadLocation:
       type: object
       title: Load Location
       description: |
         An object to capture the `Load Location`.
 
-        The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.
+        The location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, `Address` (structured address) or `AddressLines` (unstructured address).
 
         **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location.
+
+        **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
       example:
         locationName: Shanghai Shengdong International Container Terminal
         UNLocationCode: CNSGH
@@ -6859,6 +6974,19 @@ components:
           example: Building 123
         address:
           $ref: '#/components/schemas/Address'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+
+            **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         facility:
           $ref: '#/components/schemas/Facility'
         UNLocationCode:
@@ -6874,15 +7002,18 @@ components:
 
             More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
           example: NLAMS
+
     DischargeLocation:
       type: object
       title: Discharge Location
       description: |
         An object to capture the `Discharge Location`.
 
-        The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.
+        The location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, `Address` (structured address) or `AddressLines` (unstructured address).
 
         **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location.
+
+        **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
       example:
         locationName: Transnet Port Terminals Cape Town
         UNLocationCode: ZACPT
@@ -6903,6 +7034,19 @@ components:
           example: Building 123
         address:
           $ref: '#/components/schemas/Address'
+        addressLines:
+          type: array
+          maxItems: 5
+          description: |
+            Unstructured address lines, used as a fallback when structured address fields are unavailable.
+
+            **Condition:** When communicating with providers **or** consumers implementing API **v2.0.3 or earlier**, a sender implementing API **v2.0.4 or later MUST NOT** use `addressLines` as the only property to identify the location. Recipients implementing earlier versions **MAY ignore** this property.
+          items:
+            type: string
+            maxLength: 250
+            description: |
+              One line of an unstructured `Address`.
+            example: "123 Example Rd"
         facility:
           $ref: '#/components/schemas/Facility'
         UNLocationCode: