ShippingAddress versus Address

[adamroach]

The currently defined ShippingAddress interface contains several fields that semantically line up with many of the fields in the Address interface (https://www.w3.org/TR/geolocation-API-v2/#address_interface); however, most such names are unnecessarily different (with the term "region" meaning radically different things between the two interfaces).

This will lead to unnecessary developer confusion.

One approach would be to have ShippingAddress inherit from Address, and then add the other fields that we decide we need. This has the effect of splitting the "streetnumber" field from the "street" field and of adding "county" and "premises" fields, but is otherwise consistent with what is currently defined:

interface ShippingAddress : Address {
    readonly attribute FrozenArray<DOMString> additionalAddressLine;
    readonly attribute DOMString              dependentLocality;
    readonly attribute DOMString              sortingCode;
    readonly attribute DOMString              languageCode;
    readonly attribute DOMString              organization;
    readonly attribute DOMString              recipient;
};

Another approach would be to simply rename analogous fields to have identical names:

interface ShippingAddress {
    readonly attribute DOMString              country;       /* was regionCode */
    readonly attribute FrozenArray<DOMString> addressLine;
    readonly attribute DOMString              region;        /* was administrativeArea */
    readonly attribute DOMString              city;          /* was locality */
    readonly attribute DOMString              dependentLocality;
    readonly attribute DOMString              postalCode;
    readonly attribute DOMString              sortingCode;
    readonly attribute DOMString              languageCode;
    readonly attribute DOMString              organization;
    readonly attribute DOMString              recipient;
};

Arguably, we could consider "organization" and "premises" to have sufficiently close meanings to consider them the same field, but I'd be curious to hear from others about whether that would serve their purposes.

[rsolomakhin]

According to https://www.chromestatus.com/features#geolocation, Chrome implements https://www.w3.org/TR/geolocation-API/, but not https://www.w3.org/TR/geolocation-API-v2/, which includes the Address interface. Do other browsers implement it?

[tommythorsen]

I like the sound of approach number two -- renaming fields to have identical names. I don't think we should lock ourselves to having to use geolocation's Address interface directly, as some things, like the separation of street and streetNumber may turn out to be inconvenient. Being consistent with the naming of the Address interface, however, sounds like an excellent idea.

Where did "regionCode", "administrativeArea" and "locality" originally come from? Was there a good reason for the choice of these names?

[adrianba]

Geolocation v2 was abandoned a long time ago so there won't be any developer confusion. We acknowledged at the F2F that it would be possible to argue over field names, etc. for addresses pretty much forever, so we picked something that can work, based on another standard, and we should move on.

[halindrome]

Where did "regionCode", "administrativeArea" and "locality" originally come from? Was there a good reason for the choice of these names?

Specifically, these came from the OASIS xAL - the extensible address language. It is a fairly comprehensive solution that is used worldwide. And I agree with @adrianba that we should just leave it and move on. The names of these fields are largely unimportant. What is important is that there is enough flexibility to deal with world-wide requirements.

[adamroach]

Specifically, these came from the OASIS xAL - the extensible address language. It is a fairly comprehensive solution that is used worldwide.

I'm a little perplexed here. Looking at the OASIS web pages, it would appear that it uses "country" rather than "regionCode", and "localityname" instead of "locality." It also uses "thoroughfare" where we use "addressLines", and "organizationname" rather than "organization."

In particular, to the extent that I can find any reference to "region" or "region code" in any OASIS documents, it appears to always appear as a peer to "country" or "country code," with "region" designating something more like a state or province within a country.

If we want to harmonize with some other spec in this area, I can get behind that, but it's kind of nonsense to say that we're selecting somewhat nonintuitive names to align with OASIS, when it appears that we're only merely taking vague inspiration from xNAL.

[rsolomakhin]

@adamroach Hm, you're right that we're only loosely based on xNAL, but I don't feel that any existing standards serve our needs exactly. For example, in issue #6 we've considered going with IETF ECML. However, that standard has a few issues. For example:

• It breaks down the name into several constituent parts, which is not necessary for shipping addresses and makes address input forms more cumbersome.
• It has a limit of 3 lines for some reason. Even some US addresses can go over 3 street line addresses.
• It uses abbreviated name stateProv, which may be confusing to non-native language speakers.
• It does not include sub-locality (e.g. districts in China) and sorting code (France-related).

Given the sparseness of good address formats, I feel that we cannot follow any one standard to the letter. What we have now is a good enough solution, IMHO. I am open to concrete suggestions to improve it.

[adamroach]

@rsolomakhin writes:

What we have now is a good enough solution, IMHO. I am open to concrete suggestions to improve it.

I'm happy to concede that two of the differences I'm highlighting are debating bikeshed colors, but there is a major problem that we need to take care of.

On a quick survey of the various address format schemata I can find, and including the ones that I'm already familiar with, not a single one uses "region" as it is currently defined in our spec. It's confusing, incongruous with common practice, and it goes against the common meaning of the word. It will cause developer confusion. This is not an aesthetic complaint; it is a functional one.

In terms of concrete suggestions to improve the names: I gave two alternatives when I opened this issue. Even more concretely, PR #198 updates the document with the less invasive alternative. Thoughts?

[rsolomakhin]

I'm personally OK with country/region/city naming. Not sure how necessary is careOf. Can this information be placed into addressLine instead?

[adamroach]

@rsolomakhin

Not sure how necessary is careOf. Can this information be placed into addressLine instead?

Sure, just like organization and recipient could be placed into addressLine. We're making semantic separation for those, though, and we're dealing with a green field, so it seems a bit odd that we'd leave off a common use case like the need to have a c/o line in some circumstances.