Write-up proposal for shipping address fields

[adrianba]

This issue comes from wicg/paymentrequest#28 and is assigned to @rsolomakhin.

[halindrome]

I still have some ideas about this. @rsolomakhin would you prefer it as a PR or commentary here?

[rsolomakhin]

@halindrome Let's discuss your ideas here first.

[mountielee]

My Proposal
ship to title Ecom_ShipTo_Postal_Name_Prefix 4 ( 1)
ship to first name Ecom_ShipTo_Postal_Name_First 15
ship to middle name Ecom_ShipTo_Postal_Name_Middle 15 ( 2)
ship to last name Ecom_ShipTo_Postal_Name_Last 15
ship to name suffix Ecom_ShipTo_Postal_Name_Suffix 4 ( 3)
ship to company name Ecom_ShipTo_Postal_Company 20
ship to street line1 Ecom_ShipTo_Postal_Street_Line1 20 ( 4)
ship to street line2 Ecom_ShipTo_Postal_Street_Line2 20 ( 4)
ship to street line3 Ecom_ShipTo_Postal_Street_Line3 20 ( 4)
ship to city Ecom_ShipTo_Postal_City 22
ship to state/province Ecom_ShipTo_Postal_StateProv 2 ( 5)
ship to zip/postal code Ecom_ShipTo_Postal_PostalCode 14 ( 6)
ship to country Ecom_ShipTo_Postal_CountryCode 2 ( 7)
ship to phone Ecom_ShipTo_Telecom_Phone_Number 10 ( 8)
ship to email Ecom_ShipTo_Online_Email 40 ( 9)

[rsolomakhin]

@mountielee Please express your proposal in WebIDL format for ease of reading. A few questions:

1. Why do we need prefix, first, middle, last, and suffix instead of a single field for the full name? I would recommend going with a single field for the name for ease of input by user.
2. Why do we need three street address lines instead of an array of street address lines? We can recommend to limit to 3 lines for compatibility with older APIs, if that's what you intentend. An array seems like a cleaner way to express this.
3. If we're going to return the phone number and email with a shipping address, let's make it optional in the general case. I would prefer to add boolean flags "requestEmail" and "requestPhone" to PaymentOptions struct.
4. Some countries like France use a "sorting_code" field. Should we forego it?
5. Some countries like China use a "dependent_locality" or "sub_locality" field to express sub-city divisions. In China these are called "districts". Should we omit this field?

[mountielee]

my proposal was referenced by IETF ECML (https://tools.ietf.org/html/rfc4112)

example of prefix and suffix are "Mr.", "Mrs.", "Dr.", "님" these are not added by user himself normally.
single field for the full name is just presentation level.
for better data management and presentation, we need to split name field as detail as we can.

for address format , number of lines and other country cases
I have no objection.

presentation of shipping address is very culture/country sensitive.
difficult task.

[rsolomakhin]

example of prefix and suffix are "Mr.", "Mrs.", "Dr.", "님" these are not added by user himself normally.
single field for the full name is just presentation level. for better data management and presentation, we need to split name field as detail as we can.

I'm afraid that splitting the name into multiple fields will be prescriptive to user agent's UI. It's easy to combine multiple input fields into a single string for the API. However, it's difficult to correctly split a single input field into prefix, first name, middle name, last name, and suffix. Therefore, having multiple name parts in the API is likely to force the user agent UI to show multiple input fields for the name.

In Chrome we try to avoid presenting multiple input fields for the name. "Mr. James J. Bond Jr." is easier to type in one go than the following multiple steps (1) select Mr. from dropdown, (2) type "James", (3) press Tab, (4) type "J", (5) press Tab, (6) type "Bond", (7) select Jr. from dropdown.

[halindrome]

I tend to agree that multiple input fields for a name is bad UI design.
Especially on smaller devices. But I also understand why Mountie is
suggesting this - It is common to have this information stored separately.

On Thu, Mar 3, 2016 at 12:30 PM, Rouslan Solomakhin <
notifications@github.com> wrote:

example of prefix and suffix are "Mr.", "Mrs.", "Dr.", "님" these are not
added by user himself normally.
single field for the full name is just presentation level. for better data
management and presentation, we need to split name field as detail as we
can.

I'm afraid that splitting the name into multiple fields will be
prescriptive to user agent's UI. It's easy to combine multiple input fields
into a single string for the API. However, it's difficult to correctly
split a single input field into prefix, first name, middle name, last name,
and suffix. Therefore, having multiple name parts in the API is likely to
force the user agent UI to show multiple input fields for the name.

In Chrome we try to avoid presenting multiple input fields for the name.
"Mr. James J. Bond Jr." is easier to type in one go than the following
multiple steps (1) select Mr. from dropdown, (2) type "James", (3) press
Tab, (4) type "J", (5) press Tab, (6) type "Bond", (7) select Jr. from
dropdown.

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Shane McCarron
halindrome@gmail.com

[rsolomakhin]

@halindrome I propose that the merchant use their own heuristics to split this data up. I would prefer to avoid such heuristics in the user agent.

[halindrome]

I am fine with that.

On Thu, Mar 3, 2016 at 12:40 PM, Rouslan Solomakhin <
notifications@github.com> wrote:

@halindrome https://github.com/halindrome I propose that the merchant
use their own heuristics to split this data up. I would prefer to avoid
such heuristics in the user agent.

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Shane McCarron
halindrome@gmail.com

[rsolomakhin]

@mountielee + @halindrome One last question. libaddressinput provides the language of the address, which is used for formatting the address. For example, jp-JP address has country on top, but jp-Latn address has country on bottom. Do you think merchants will find the "language" field useful?

[halindrome]

Now I am confused... and I know I can (and will) look at the draft again. But is this data input to the payment request from the merchant, input to the payment method from the user agent, output from one or more of those, or all of the above?

If it is data that is being sent from the user agent to the merchant, then sure - the language is something that will be helpful. If it is being sent from the merchant (because they KNOW who you are and you have selected a shipping address on that end) or sent from the user agent to the payment method, then.... I don't think I care very much. It can't hurt to include it. I would ensure it was optional though.

On a related note, I know that according to old issue 28 I am on the hook to do WebIDL for the PostalAddress from Schema.org and/or xAL. I am working on that now.

[rsolomakhin]

If it is data that is being sent from the user agent to the merchant, then sure - the language is something that will be helpful.

This. User agents provides the shipping address to the merchant.

[rsolomakhin]

Based on these discussions, here's @mountielee's proposal in WebIDL form. Three questions:

1. Should we rename dependentLocality into subLocality?
2. Should we rename stateProv into stateProvince?
3. Is countryCode coming from ISO 3166 Alpha-2?

interface ShippingAddress {
    readonly DOMString name;
    readonly DOMString company;
    readonly sequence<DOMString> streetLines;
    readonly DOMString dependentLocality;
    readonly DOMString city; 
    readonly DOMString stateProv;
    readonly DOMString postalCode;
    readonly DOMString sortingCode;
    readonly DOMString countryCode;
    readonly DOMString phone;
    readonly DOMString email;
};

dictionary PaymentOptions {
    boolean requestShipping = false;
    boolean requestPhone = false;
    boolean requestEmail = false;
};

[mountielee]

as Non-Native English User,
subLocality is better than dependentLocality
stateProvince is better than stateProv
2-digits of ISO3166 Aopha02 is common for countryCode.

On Fri, Mar 4, 2016 at 9:40 AM, Rouslan Solomakhin <notifications@github.com

wrote:

Based on these discussions, here's @mountielee
https://github.com/mountielee's proposal in WebIDL form. Three
questions:

1. Should we rename dependentLocality into subLocality?
2. Should we rename stateProv into stateProvince?
3. Is countryCode coming from ISO 3166 Alpha-2
   https://www.iso.org/obp/ui/#search/code/?

interface ShippingAddress {
readonly DOMString name;
readonly DOMString company;
readonly sequence streetLines;
readonly DOMString dependentLocality;
readonly DOMString city;
readonly DOMString stateProv;
readonly DOMString postalCode;
readonly DOMString sortingCode;
readonly DOMString countryCode;
readonly DOMString phone;
readonly DOMString email;
};

dictionary PaymentOptions {
boolean requestShipping = false;
boolean requestPhone = false;
boolean requestEmail = false;
};

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Mountie Lee

PayGate
CTO, CISSP
Tel : +82 2 2140 2700
E-Mail : mountie@paygate.net
Twitter : mountielee

[mountielee]

language field is useful. I'm sure.

do we also need to consider encodings?

for example,
to present korean, EUC-KR or UTF-8 can be used.
encoding is on merchant's choice.

On Fri, Mar 4, 2016 at 4:16 AM, Rouslan Solomakhin <notifications@github.com

wrote:

@mountielee https://github.com/mountielee + @halindrome
https://github.com/halindrome One last question. libaddressinput
https://github.com/googlei18n/libaddressinput provides the language of
the address, which is used for formatting the address. For example, jp-JP
address has country on top, but jp-Latn address has country on bottom. Do
you think merchants will find the "language" field useful?

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Mountie Lee

PayGate
CTO, CISSP
Tel : +82 2 2140 2700
E-Mail : mountie@paygate.net
Twitter : mountielee

[rsolomakhin]

do we also need to consider encodings?

Everyone on the web is using UTF-8. (If not, they should be.) Let's stick with UTF-8 everywhere.

[rsolomakhin]

Updated based on @mountielee's comments:

interface ShippingAddress {
    readonly DOMString name;
    readonly DOMString company;
    readonly sequence<DOMString> streetLines;
    readonly DOMString subLocality;
    readonly DOMString city; 
    readonly DOMString stateProvince;
    readonly DOMString postalCode;
    readonly DOMString sortingCode;
    readonly DOMString countryCode;
    readonly DOMString phone;
    readonly DOMString email;
};

dictionary PaymentOptions {
    boolean requestShipping = false;
    boolean requestPhone = false;
    boolean requestEmail = false;
};

I'm OK with this proposal. @zkoch , do you have any opinions on phone/email here?

[mountielee]

http://www.gmarket.co.kr/ is one of biggest marketplace in Korea subsidiary
of eBay.
they use EUC-KR (non UTF-8) over 10 years.

http://www.rakuten.co.jp/ is one of biggest marketplace in Japan.
they use EUC-JP (non UTF-8) over 10 years.

http://www.taobao.com/ is one of biggest marketplace in China.
they use GBK (non UTF-8) over 10 years.

switching encoding is very sensitive.

if we insist to use UTF-8 only, many merchants will lost opportunity using
shipping address feature of web payments.

On Sat, Mar 5, 2016 at 2:33 AM, Rouslan Solomakhin <notifications@github.com

wrote:

do we also need to consider encodings?

Everyone on the web is using UTF-8. (If not, they should be.) Let's stick
with UTF-8 everywhere.

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Mountie Lee

PayGate
CTO, CISSP
Tel : +82 2 2140 2700
E-Mail : mountie@paygate.net
Twitter : mountielee

[halindrome]

That's a really good point. Are you proposing that the API platform somehow transform the data from the end user's encoding of choice to the merchant's encoding of choice? I mean, I suppose that happens today, but in a very subtle way. The information is stored in the user agent in UTF-8, but the merchant-provided form is in whatever encoding the merchant chose. So when auto-filling a form, a user agent is perforce converting to the merchant's encoding.

Such conversion is not typically done in JSON however. The returned data is almost always in UTF-8. It is just sort of expected.

Can anyone comment on my supposition that user agents that autofill are just dealing with this today? And if so, how are they doing it?

[mountielee]

I think payment mediator will pass message to payment app ASIS.
payment app will handle encoding issue (implementation level issue.
out-of-scope, I think)

just add encoding parameter as optional to message WebIDL.

regards
mountie

On Sat, Mar 5, 2016 at 1:09 PM, Shane McCarron notifications@github.com
wrote:

That's a really good point. Are you proposing that the API platform
somehow transform the data from the end user's encoding of choice to the
merchant's encoding of choice? I mean, I suppose that happens today, but in
a very subtle way. The information is stored in the user agent in UTF-8,
but the merchant-provided form is in whatever encoding the merchant chose.
So when auto-filling a form, a user agent is perforce converting to the
merchant's encoding.

Such conversion is not typically done in JSON however. The returned data
is almost always in UTF-8. It is just sort of expected.

Can anyone comment on my supposition that user agents that autofill are
just dealing with this today? And if so, how are they doing it?

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Mountie Lee

PayGate
CTO, CISSP
Tel : +82 2 2140 2700
E-Mail : mountie@paygate.net
Twitter : mountielee

[halindrome]

And should the default value for encoding be the encoding of the web page the request was made from? Hmm. I can't decide if that violates the "principle of least surprise" or not [1]. On the one hand, if I am a naive web merchant and I have not internationalized my site, my encoding is likely to be something silly. On the other hand, if I am such a merchant I am probably using some sort of off the shelf shopping cart module on my site, and that module is going to expect UTF-8.

If we are going to go down this road, my inclination would be to have the default be the encoding of the page from which the request was made, and that the field is always populated in the response to tell the consumer of the returned data the encoding of that data. I would also be open to the default always being "UTF-8". The requestor can override that with an optional parameter. And the response should always indicate the encoding of the response. That way the receiving library can always pick apart the message regardless.

Thoughts?

[1] https://en.wikipedia.org/wiki/Principle_of_least_astonishment

[mountielee]

I'm thinking

• domain bounded payment app or others.

if payment app is domain bounded, encoding will follow service provider's
policy
if payment app is not domain bounded, payment app should handle multiple
encodings.

still we are discussing same-origin policy of payment app.

one of basic approaches I agree is
set "UTF-8" as default and allow requestor override that with an optional
encoding parameter.

regards
mountie

On Sun, Mar 6, 2016 at 1:52 AM, Shane McCarron notifications@github.com
wrote:

And should the default value for encoding be the encoding of the web page
the request was made from? Hmm. I can't decide if that violates the
"principle of least surprise" or not [1]. On the one hand, if I am a naive
web merchant and I have not internationalized my site, my encoding is
likely to be something silly. On the other hand, if I am such a merchant I
am probably using some sort of off the shelf shopping cart module on my
site, and that module is going to expect UTF-8.

If we are going to go down this road, my inclination would be to have the
default be the encoding of the page from which the request was made, and
that the field is always populated in the response to tell the consumer of
the returned data the encoding of that data. I would also be open to the
default always being "UTF-8". The requestor can override that with an
optional parameter. And the response should always indicate the encoding of
the response. That way the receiving library can always pick apart the
message regardless.

Thoughts?

[1] https://en.wikipedia.org/wiki/Principle_of_least_astonishment

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Mountie Lee

PayGate
CTO, CISSP
Tel : +82 2 2140 2700
E-Mail : mountie@paygate.net
Twitter : mountielee

[rsolomakhin]

Reading up on this topic indicates that we do not have to worry about encoding for our API. Speaking JavaScript states that browsers follow the web-page's encoding when loading JavaScript:

When a web browser loads a source file via a script tag, it determines the encoding as follows:
If the file starts with a BOM, the encoding is a UTF variant, depending on what BOM is used.
Otherwise, if the file is loaded via HTTP(S), then the Content-Type header can specify an encoding, via the charset parameter. Otherwise, if the script tag has the attribute charset, then that encoding is used. Otherwise, the encoding of the document is used, in which the script tag resides.

This makes sense, because I do not recall any JavaScript APIs that let you customize text encoding.

Also please note that payment apps are not specified to deal with shipping addresses. For example, Chrome is likely to provide autofill addresses that it already stores.

[halindrome]

Regards your last point... I think I have to disagree. We have not specified the scope of a payment app, but in particular as the verifiable claims work expands I envision payment apps providing all sorts of information to the merchant via the user agent. Digital coupons, loyalty cards, addresses. Actually, if you think about it, it happens today already. Consider "paypal". On any merchant site I use that accepts paypal, if I click that link it invokes paypal (the payment app) to authorize the transaction. Paypal returns the confirmation and my shipping address to the merchant. We cannot preclude this sort of implementation. The user agent can become the trusted conduit, but we cannot require that it be the only source of any of the information.

[dlongley]

The user agent can become the trusted conduit, but we cannot require that it be the only source of any of the information.

👍

[rsolomakhin]

@halindrome Good point. Since no such payment apps exist yet, can we require them to use unicode for communication to the user agent?

[halindrome]

Absolutely! UTF-8 only? I don't remember my ISO 10646 all that well. Is
UTF-16 still a thing we might need to permit / support? Also, are Windows
native apps still using CP-1252? And is that an issue for them? I can't
imagine that it would be; they have to communicate with the real world, and
that speaks Unicode.

On Mon, Mar 7, 2016 at 2:54 PM, Rouslan Solomakhin <notifications@github.com

wrote:

@halindrome https://github.com/halindrome Good point. Since no such
payment apps exist yet, can require them to use unicode for communication
to the user agent?

—
Reply to this email directly or view it on GitHub
#6 (comment)
.

Shane McCarron
halindrome@gmail.com

[rsolomakhin]

@adrianba For Windows question.

are Windows native apps still using CP-1252?

[adrianba]

Web IDL is clear on the definition of DOMString. JavaScript strings are treated as UTF-16. Any encoding after that is up to whatever code is doing serialisation.

[dlongley]

I guess Web IDL just makes me sad then :(

I think null makes more sense than an empty string. An empty string is an actual value, whereas null indicates "no value".

[rsolomakhin]

Sounds good.

[adrianba]

If we wanted to we could create a method that returns a dictionary instead of an attribute that has an interface but I'm not sure it is a good idea (it would need to be a method to indicate that the dictionary instance would be different every time you call it).

The reason I think having an interface is better is because it is possible to detect the presence of attributes in the interface and if we add new things in future you can feature detect if they are supported.

I think attributes that can be null is fine.

[rsolomakhin]

Also note that dictionaries cannot be nullable, so ShippingAddress? shippingAddress; in PaymentRequest object has to be an interface.

[adrianhopebailie]

@adrianba Can you explain the reasoning for not using a dictionary?

I don't really follow what you said above. I understand the value of checking for the presence of attributes as a crude feature detection but isn't this a return object that the website will simply consume and develop logic around for the generation of the payment request?

[adrianba]

Checking for attributes isn't crude feature detection - it's most likely the best type of feature detection. By having an interface in the type system, you can interrogate the presence of attributes at run time. A dictionary returned by a method is indistinguishable from a JavaScript object (in our implementation it is simply a JavaScript object) and you can't infer anything from it.

So if we add new attributes in future and I want to be able to tell if my code is running in a browser that supports those new attributes then I need an interface to interrogate.

[adrianhopebailie]

My comment wasn't really about whether this method of feature detection is crude or not but more about whether this object is the right one for developers to use for feature detection.

What this thread suggests is that developers using the payments API must initiate a payment request and request shipping data collection, then interrogate the shape of the return object that to determine what version of the payments API they are working with. I'm a firm -1 on that.

1. This forces developers to request a user's shipping address in order to do feature detection.
2. Wouldn't developers perform their feature detection logic long before this point in the process?
3. Would changes to the API always result in measurable changes to the shape of the shipping address object so that developers can use this object as a way of detecting this?

I agree that feature detection is required but I'm not sure that the shape of this object is the right place to facilitate it.

[adrianhopebailie]

Via email @rsolomakhin said:

We have two proposals at the moment:

1. OASIS xAL based names: regionCode, administrativeArea, locality, etc.
2. IETF ECML based names: countryCode, stateProvince, city, etc.

I've been working with OASIS names in Chrome, but changing to IETF would not be a big deal for Chrome.

We need to get some finality on this to allow implementers to start experimenting with the API.

As long as they cater for all jurisdictional peculiarities (which seems likely as they are both international standards) I'd recommend we use whatever the browser vendors are most familiar with as this will allow them to leverage the stored addresses they already have to streamline this data collection process.

I also assume that the vendors feel comfortable with rendering an appropriate input control for different jurisdicitions and mapping this back to this standardized return format.

PROPOSAL

We have heard that OASIS xAL based names are already used by one browser vendor so I propose we standardize on these and PR is submitted to the API spec that expresses this format using WebIDL.

[adrianba]

What this thread suggests is that developers using the payments API must initiate a payment request and request shipping data collection, then interrogate the shape of the return object that to determine what version of the payments API they are working with. I'm a firm -1 on that.

You don't have to generate a request to interrogate the shape of a type - that's actually why it being an interface is necessary. You can't interrogate a dictionary because it is just a JavaScript object.

I agree that feature detection is required but I'm not sure that the shape of this object is the right place to facilitate it.

That's how almost all reliable feature detection is done.

[rsolomakhin]

@adrianhopebailie wrote:

I also assume that the vendors feel comfortable with rendering an appropriate input control for different jurisdictions and mapping this back to this standardized return format.

This should not be a problem. If a vendor does not feel comfortable rendering the input contorls, they can use libaddressinput for this purpose. Chrome is using it internally. The Apache 2.0 license should be permissive enough to use any part of libaddressinput in both open and closed source projects. The version that I linked has C++ and Java implementations. There're PHP and Python forks out there as well.

[nickjshearer]

The Apache 2.0 license should be permissive enough to use any part of libaddressinput in both open and closed source projects.

I don't believe the actual data consumed by libaddressinput has any explicit license (https://groups.google.com/forum/#!msg/libaddressinput-discuss/kvhArVA2KEQ/jnz1qvEyPR8J), or for that matter is available in a public dump, so it's not as permissive as the client library makes out. I would love to see that data released and/or the license position clarified.

Anyway, in the interest of moving this along I think I'm content with OASIS.

[rsolomakhin]

I don't believe the actual data consumed by libaddressinput has any explicit license (https://groups.google.com/forum/#!msg/libaddressinput-discuss/kvhArVA2KEQ/jnz1qvEyPR8J)

That is correct.

so it's not as permissive as the client library makes out.

Sorry about that.

I would love to see that data released and/or the license position clarified.

I will prod the data maintainers to put a proper license on it.

[not] available in a public dump

The (unlicensed) data is available for browsing from https://i18napis.appspot.com/address. Chrome loads the same data in bulk from https://i18napis.appspot.com/ssl-aggregate-address/, for example, the California data is in https://i18napis.appspot.com/ssl-aggregate-address/data/US/CA.

Keep in mind that i18napis.appspot.com does not have an SLI. Do not rely on it being there all the time or supporting unlimited QPS.

[rsolomakhin]

If there're no further objections, I will submit the OASIS xAL fields names as a pull request to PaymentRequest draft spec (regionCode, administrativeArea, locality, etc).

[rsolomakhin]

Created the pull request #147. I welcome your suggestions for better wording to describe the field names.

[adrianba]

Fixed by #147. Please file PR with any updated descriptions.

[nickjshearer]

I will prod the data maintainers to put a proper license on it.

Thanks! I'm sure it'll be appreciated.