adjust location spec

1 files changed, 38 insertions, 16 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 47f94180..b73107a2 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -2534,8 +2534,12 @@ The contract terms must have the following structure:
     // Exchanges that the merchant accepts even if it does not accept any auditors that audit them.
     exchanges: Exchange[];
 
-    // Map from labels to locations
-    locations: { [label: string]: [location: Location], ... };
+    // Delivery location for (all!) products.
+    delivery_location?: Location;
+
+    // Time indicating when the order should be delivered.
+    // May be overwritten by individual products.
+    delivery_date?: Timestamp;
 
     // Nonce generated by the wallet and echoed by the merchant
     // in this field when the proposal is generated.
@@ -2601,12 +2605,6 @@ The `Product` object describes the product being purchased from the merchant. It
 
     // time indicating when this product should be delivered
     delivery_date?: Timestamp;
-
-    // where to deliver this product. This may be an URL for online delivery
-    // (i.e. 'http://example.com/download' or 'mailto:customer@example.com'),
-    // or a location label defined inside the proposition's 'locations'.
-    // The presence of a colon (':') indicates the use of an URL.
-    delivery_location?: string;
   }
 
 .. ts:def:: Tax
@@ -2623,28 +2621,52 @@ The `Product` object describes the product being purchased from the merchant. It
 
   interface Merchant {
     // label for a location with the business address of the merchant
-    address: string;
+    address: Location;
 
     // the merchant's legal name of business
     name: string;
 
     // label for a location that denotes the jurisdiction for disputes.
     // Some of the typical fields for a location (such as a street address) may be absent.
-    jurisdiction: string;
+    jurisdiction: Location;
   }
 
 
 .. ts:def:: Location
 
+  // Delivery location, losely modeled as a subset of
+  // ISO20022's PostalAddress25.
   interface Location {
+    // Nation with its own government.
     country?: string;
-    city?: string;
-    state?: string;
-    region?: string;
-    province?: string;
-    zip_code?: string;
+
+    // Identifies a subdivision of a country such as state, region, county.
+    country_subdivision?: string;
+
+    // Identifies a subdivision within a country sub-division.
+    district?: string;
+
+    // Name of a built-up area, with defined boundaries, and a local government.
+    town?: string;
+
+    // Specific location name within the town.
+    town_location?: string;
+
+    // Identifier consisting of a group of letters and/or numbers that
+    // is added to a postal address to assist the sorting of mail.
+    post_code?: string;
+
+    // Name of a street or thoroughfare.
     street?: string;
-    street_number?: string;
+
+    // Name of the building or house.
+    building_name?: string;
+
+    // Number that identifies the position of a building on a street.
+    building_number?: string;
+
+    // Free-form address lines, should not exceed 7 elements.
+    address_lines?: string[];
   }
 
 .. ts:def:: Auditor