Add create a ContactAddress from user-provided input (#77)

index.bs

@@ -453,6 +453,106 @@ interface ContactsManager {
     remove the UI and return a [=list=] of the selected contacts as [=user contacts=].
 </div>
 
+# Creating a `ContactAddress` from user-provided input # {#creating-contactaddress}
+
+The steps to <dfn export>create a `ContactAddress` from user-provided input</dfn>
+are given by the following algorithm.
+The algorithm optionally takes a [=list=] |redactList|.
+If the |redactList| is not passed, it defaults to an [=list/empty=] [=list=].
+
+NOTE: The |redactList| optionally gives user agents
+  the possibility to limit the amount of personal information
+  about the recipient that the API shares with the requesting application.
+The resulting {{ContactAddress}} object provides enough information
+  to perform necessary operations
+  such as communication or service delivery,
+  but, in most cases,
+  not enough information to physically locate and uniquely identify the recipient.
+Unfortunately, even with the |redactList|,
+  recipient anonymity cannot be assured.
+  This is because in some countries
+  postal codes are so fine-grained that they can uniquely identify a recipient.
+
+<div class="algorithm">
+
+  1. Let |details| be the [=map=] «
+      "addressLine" → empty [=list=],
+      "country" → "",
+      "phone" → "",
+      "city" → "",
+      "dependentLocality" → "",
+      "organization" → "",
+      "postalCode" → "",
+      "recipient" → "",
+      "region" → "",
+      "sortingCode" → ""
+     ».
+  1. If |redactList| doesn't [=list/contain=] "addressLine",
+     set |details|["addressLine"] to the result of splitting the user-provided address line into a [=list=].
+
+     NOTE: How to split an address line is locale dependent
+     and beyond the scope of this specification.
+
+  1. If |redactList| doesn't [=list/contain=] "country",
+     set |details|["country"] to the user-provided [=physical address/country=] as an upper case [[ISO3166-1]] alpha-2 code.
+  1. If |redactList| doesn't [=list/contain=] "phone",
+     set |details|["phone"] to the user-provided [=physical address/phone number=].
+
+     NOTE: To maintain users' privacy,
+     implementers need to be mindful
+     that a contact address's associated phone number
+     might be different or the same from that of the end user's.
+     As such,
+     implementers need to take care
+     to not provide the end user's phone number without the end user's consent.
+
+  1. If |redactList| doesn't [=list/contain=] "city",
+     set |details|["city"] to the user-provided [=physical address/city=].
+  1. If |redactList| doesn't [=list/contain=] "dependentLocality",
+     set |details|["dependentLocality"] to the user-provided [=physical address/dependent locality=].
+  1. If |redactList| doesn't [=list/contain=] "organization",
+     set |details|["organization"] to the user-provided recipient [=physical address/organization=].
+  1. If |redactList| doesn't [=list/contain=] "postalCode",
+     set |details|["postalCode"] to the user-provided [=physical address/postal code=].
+     Optionally, redact part of |details|["postalCode"].
+
+     NOTE: [=physical address/Postal codes=]
+     in certain countries can be so specific
+     as to uniquely identify an individual.
+     This being a privacy concern,
+     some user agents only return the part of a postal code
+     that they deem sufficient for the application's needs.
+     This varies across countries and regions,
+     and so the choice to redact part,
+     or all,
+     of the postal code is left to the discretion of implementers
+     in the interest of protecting users' privacy.
+
+  1. If |redactList| doesn't [=list/contain=] "recipient",
+     set |details|["recipient"] to the user-provided [=physical address/recipient=] of the contact information.
+  1. If |redactList| doesn't [=list/contain=] "region",
+     set |details|["region"] to the user-provided [=physical address/region=].
+
+     NOTE: In some countries (e.g., Belgium)
+     it is uncommon for users to include a [=physical address/region=]
+     as part of a [=physical address=]
+     (even if all the regions of a country are part of [[ISO3166-2]]).
+     As such,
+     when the user agent knows that the user is inputting the address
+     for a particular country,
+     it might not provide a field for the user to input a [=physical address/region=].
+     In such cases,
+     the user agent returns an empty string for both {{ContactAddress}}'s
+     {{ContactAddress/region}} attribute - but the address can still serve its intended purpose
+     (e.g., be valid for communication or service delivery).
+
+  1. If |redactList| doesn't [=list/contain=] "sortingCode",
+     set |details|["sortingCode"] to the user-provided [=physical address/sorting code=].
+  1. Return a newly created {{ContactAddress}} whose attribute's value's match those in |details|.
+</div>
+
+
+
 # Acknowledgments # {#acknowledgments}
 
 There has been multiple earlier attempts to standardize a Contacts API for the web and this