Payment-request: Request to remove 'careOf' field from the PaymentAddress interface

Created on 2 Sep 2016 · 8Comments · Source: w3c/payment-request

Summary: The PaymentAddress interface has a careOf field which is non-standard (no well-known address standards support it, see below). The careOf field is unnecessary, the recipient and organization fields sufficiently support all necessary use cases. Adding careOf poses significant issues in terms of interoperability with existing postal address schemas and APIs.

I’m with the internationalization group at Google who support all aspects of address input, validation, conversion between schemas, and formatting for all countries, including the open source libaddressinput.

careOf was added in #198 without much discussion. Every new field has potential benefit but may also have a non-trivial maintenance and interoperability cost. As such we think it's important that the value of any new fields is examined carefully and weighed against the cost. The other fields in PaymentAddress are there for very solid, defensible reasons. E.g. name & organization are there because depending on the purpose, these are used differently and many major APIs / address schemas have these two fields (or equivalents thereof).

careOf is problematic because it requires everyone handling addresses to retain the field type, decide where in input/editing forms and formatting it goes, offer UI for it and internationalize all of this for hundreds of countries and decide what to do with it when converting to & from all the other schemas / APIs which don’t have this field.
This would be fine if it provided enough value to outweigh the cost. But the value is unclear and the interoperability & handling cost is very significant. Companies / existing solutions can handle recipient and organization fields. Which service / library can format / validate addresses in 200+ countries with such a careOf field?

List of major postal address / shipping schemas & APIs none of which have a careOf field (or similar) as a separate field but do have a name/contact and a organization/company/firm field:

libaddressinput (open-source library) has organization & recipient. (link)
_H-card / adr microformat_ have a p-name and a p-org field. (adr depends on the parent h-card for addressee fields)
USPS’ own “International Label APIs” doesn’t have a careOf field. They have ‘ToFirm’ and ToName (or rather ‘ToFirstName’, ‘ToLastName’) fields. (link)
Fedex has a field for the contact & CompanyName, nothing separate for careOf (link, see “Table 57: Recipient Information Elements”)
UPS has AttentionName and CompanyName fields in ShipTo (zip download, see “Shipping Package XML Developer Guide.pdf” section /ShipmentConfirmRequest/Shipment/ShipTo)
easypost have a field for the name and for the company. (link)
Authorize.net has a firstName, lastName & company in its shipTo address fields. (link)
Android Pay’s UserAddress has CompanyName and Name fields. (link)
xNAL 3.0 (as part of OASIS CIQ) models it as “Addressee” (0+) which can have PartyName (person or org or unstructured) and a DependencyName (same). xNAL is a very powerful schema (and flexible regarding granularity), not the simplest to use (in its full spec). Yet it doesn’t break out careOf as a separate field. (link)

We don't know of any standard / API which has these 3 fields (careOf, recipient, organization), irrespective of the exact field name (e.g. recipient vs. name vs. contact). We are aware of schemas / APIs which only have a single name/contact field rather than also having a separate field for organization, yet organization is there in the above mentioned APIs / schemas for good reasons.

We think there’s overwhelming evidence against a careOf field. If that’s not the case, please present the case to have a careOf field.

To summarize: The recipient field is good enough (together with the organization field). The recipient field is and can be used instead of the careOf field.

Thanks for your consideration,
Andy on behalf of the team behind libaddressinput, address formatting in Google Maps, etc.

Source

andyst

👍5

Most helpful comment

It seems to me that both sides are making good points: 1.) @adamroach is saying that if users want to use the careOf field, they shouldn't have to figure out how to shoehorn it into one of the other fields (e.g. recipient). But this is mostly on a user level, not a spec level. 2.) @andyst is saying that careOf doesn't belong in the spec itself and it seems that there is strong support for that being true.

I think that both use cases can be accommodated. It's already true that the form fields that users see do not necessarily reflect what is in the underlying spec (e.g. most residents of the US would not know what to fill in on a region field, they would expect to see "State"). So I think we can remove "careOf" from the actual specification, and let it be an example of localizing a form.

So as an implementation decision, the browser could show a form that looked like:

<form>

  <label>Recipient name:</label>
  <input type="text" name="recipient-name" />

  <label>careOf</label>
  <input type="text" name="care-of" />

</form>

But when the address gets normalized to the underlying spec format, it would look like:

{
  "recipient": "Zach Koch \n careOf Alice Bob"
}

Or something like that anyway. :)

zkoch on 13 Sep 2016

👍4

All 8 comments

I'm sympathetic to the issues you describe regarding interfacing with existing libraries.

The fact remains that users must make use of c/o in certain circumstances (I sent Zach a reference to USPS guidelines referring to some of these circumstances, but can't find them at the moment). We can either push the complexity of shoehorning the c/o value into some appropriate place to the user (which is confusing and frustrating for the user), or we can require applications to perform this mapping (e.g., by appending "c/o Name" to the name fields, or prepending it to the company fields).

So, we're really discussing whether to push this complexity on to users, or to push it onto app developers. At which point I would turn to https://www.w3.org/TR/html-design-principles/#priority-of-constituencies to break the tie.

adamroach on 8 Sep 2016

I found the references I provided Zach earlier. To establish as fact that certain users must make use of "care of" for proper mail handling:

Section 2.8 bullet "b" here lays out a requirement (using the term "must") to use a "care of" format:
http://pe.usps.com/Archive/HTML/DMMArchive20030810/D041.htm

Section 1.1.8 bullet "h" gives "care of" legal force here:
http://pe.usps.com/text/dmm300/508.htm

So the need for such a field really isn't in question: it only comes down to whether users need to wedge c/o in somewhere, or whether software does.

adamroach on 8 Sep 2016

Perhaps "care of" could fit into something like "alternateName": https://schema.org/PostalAddress

dlongley on 8 Sep 2016

Thanks for your responses, @adamroach and @dlongley!

I think the above comparison of postal address schemas / APIs has shown that the consensus in the industry is that there is no need for a careOf field. This strongly supports a different reading / conclusion than the interpretation that there must be a careOf field.

Not a single of these schemas / APIs has a careOf field.
Even USPS' own "International Label APIs" don’t have a careOf field but do have fields for name & firm. (see reference in first post)
- E.g. your referenced USPS doc (http://pe.usps.com/Archive/HTML/DMMArchive20030810/D041.htm) is part of the “Domestic Mail Manual” and this section is about “D041 Customer Mail Receptacles - 2.0 Curbside Mailboxes - 2.8 More Than One Family”.
- It makes a point about "care of" in address labels for the USA. It doesn't make a point about address APIs / schemas.
- (There are many other countries and even the USPS has many other guidelines / manuals.)

Why try to innovate in address schemas here by adding a the careOf field?

I believe the goal to be to follow existing standards / best practices as much as possible to work with existing address schemas / APIs (shipping, payment gateways / APIs).
Not a single other established schema or API has such a careOf field.
I don’t see sufficient evidence to diverge from the industry’s best practice in such a significant way.

andyst on 13 Sep 2016

👍1

So as an implementation decision, the browser could show a form that looked like:

<form>

  <label>Recipient name:</label>
  <input type="text" name="recipient-name" />

  <label>careOf</label>
  <input type="text" name="care-of" />

</form>

But when the address gets normalized to the underlying spec format, it would look like:

{
  "recipient": "Zach Koch \n careOf Alice Bob"
}

Or something like that anyway. :)

zkoch on 13 Sep 2016

👍4

I think @zkoch's proposal is a reasonable compromise, assuming we have language in the spec that mentions this treatment of recipient name. Specifically: if we decide this is the solution for "care of" handling, then we need mention that the recipient name field may, under certain circumstances, contain multiline information.

adamroach on 15 Sep 2016

Thank you very much, @zkoch & @adamroach. That's a good compromise. Thanks a lot for the discussion!

andyst on 15 Sep 2016

Though we did not record a formal decision, I believe there was consensus on today's WPWG call [1] to handle this through user interface. Zach took an action to update the spec with a note on handling multi-line data, with careOf as an example.

Ian

[1] https://www.w3.org/2016/09/15-wpwg-minutes#item04