diff --git a/index.bs b/index.bs index b67133e..0679e12 100644 --- a/index.bs +++ b/index.bs @@ -453,6 +453,106 @@ interface ContactsManager { remove the UI and return a [=list=] of the selected contacts as [=user contacts=]. +# Creating a `ContactAddress` from user-provided input # {#creating-contactaddress} + +The steps to create a `ContactAddress` from user-provided input +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. + +
+ + 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|. +
+ + + # Acknowledgments # {#acknowledgments} There has been multiple earlier attempts to standardize a Contacts API for the web and this