Update vanity_number in example location

[anselmbradford]

The vanity_number in the example location data is set to 222-555-INFO, however, since the vanity number doesn't include any automatic formatting, the expectation for Ohana Web Search demo purposes is that it would be manually formatted to fit with regular phone number formatting. This means it should be updated to (222) 555-INFO.

[monfresh]

If Ohana Web Search doesn't format vanity numbers, I would argue that there should be a non-formatted example such as the one that exists so that people can see that there is a formatting difference between regular and vanity numbers.

The API shouldn't be expected to format vanity numbers in any particular way, unless that is mandated by the Open Referral spec, but I wouldn't expect that to happen since vanity numbers are not consistent.

[anselmbradford]

I think the formatting (or lack thereof) for the vanity number is best advertised in the admin interface where those values are edited. That being said, there is a non-formatted example in /locations/admin-test-org/admin-test-location. However, since the demos are supposed to be examples of real-world use there should also be a properly formatted entry, which I'd like to see in Example Location since I design against that entry primarily.

[monfresh]

"Non-formatted" doesn't mean anything for vanity numbers because there is no specific formatting expected of them. The way the example vanity number is currently returned by the API already reflects real-world usage. Your desired formatting is not representative of how these numbers are typically entered. Here are all the vanity numbers from the San Mateo County API. Not a single one uses parentheses:

800 777-PLAN 877 WNV-BIRD 800-72-TOXIC 800 I-AM-LOST 800 A-WAYOUT 650 692-RAPE 650-342-CALL 800 ID ALERT 415 863-AIDS 800 FOR-AIDS 650 344-LION 800 934-CURE 415 333-HELP 415-289-SEAL 415 502-TEST 866 HIV-INFO 800 KEEPBAY 800-78-CRIME 800-47-ARSON 800-47-DRUGS 800-87-FRAUD 888 NHF-5552 888-FOX-TERR 415-982-DECO 800-952-JOBS 408 993-BAND 800 LANGUAGE 408 287-HOPE 888 818-HOPE 877 488-KIDS 800 334-ODOR 800 EXHAUST 800 ELECT-US 866 GO-EDGEWOOD 800 473-BASH 650 342-DANC 888 Kid-Hope 888 41-BRICK 800 GO-LIVER 800-927-HELP 800 4-CANCER 888 GA-HELPS 888 LPA-2001 800 222-LUNG 800-994-NDGW 650 327-MILK 800-LOOKOUT 425-771-SEEK 415 808-HELP 800-NOBUTTS 800-45NOFUME 800-VICTIMS 800-CLEANUP 800 675-TIES 800-CLEANUP 408 676-READ 408 299-KIDS 800 273-TALK 800-FED-INFO 800-870-FORM

I picked one randomly and looked it up on their site. They don't use parentheses either: http://www.cancer.gov/global/contact

[anselmbradford]

I don't understand the context for this? Unless I'm mistaken all or most of these numbers all came from the PLS data, which we have no idea how and by whom it was originally entered. If these were entered via the admin interface we should note the formatting in there. And what does a 3rd party website have to do with how we display phone numbers? We display phone numbers in (XXX) XXX-XXXX format and should encourage that for vanity numbers too since we can't enforce it. Since they're arbitrary I'm just asking for one entry to change so I can design around it, I'm not understanding what's controversial about that when there are other entries with different formats.

[monfresh]

The data exposed by the API will have been entered in some outside system, such as a CSV, before being imported into the API. Therefore, vanity numbers will by default be formatted the way they were entered by someone, i.e. most likely without parentheses.

Therefore, given that vanity numbers in real-world usage do not typically come formatted the way you would like them to be, you should be designing around the way they are likely to come to you.

Ohana Web Search is only one client that could potentially use the API and should not dictate the formatting of vanity numbers. If anything, what should be encouraged is no special formatting at all so that a client can apply their own formatting.

Based on SMC data, it seems like vanity numbers all start with 3-digits, so if you want to assume that all vanity numbers are like that, then you can put parentheses around the first 3 digits. That would be the only formatting that should be applied because the rest of the vanity number does not consistently follow the XXX-XXXX pattern. For example, 800-45NOFUME should not become (800) 45N-OFUM.

[monfresh]

We had already discussed the difficulty, if not impossibility, of formatting vanity numbers consistently and I thought we had agreed that they should not be formatted.

[monfresh]

I'm closing this since this is not an API issue. Since the Open Referral spec does not mandate any particular format for vanity numbers, clients should be prepared to deal with any variety of formatting. You cannot claim that the example vanity number is not properly formatted if there are no formatting rules.

The example number is representative of how phone numbers are entered by most humans. In the entire SMC database, not a single number (both regular and vanity) encloses the first 3 digits in parentheses. Most people will not go through the trouble of typing in the parentheses when they can just type in the numbers directly. And I wouldn't encourage the use of parentheses, or use JS in the admin interface or server-side post-processing to automatically add parentheses because some clients might prefer plain formatting from the API.

[anselmbradford]

It seems like this issue got conflated with enforcing a format for the vanity_number. This was about updating an example data entry. Sure the vanity_number could come through in any number of formats, but if the example data was from a real world instance, the entry could be cleaned up in the admin interface to any format desired (and I would consider a desirable formatting to be one that matches the existing formatting of the phone numbers in the demo we provide). For a field that has no formatting rules, I'm not clear on why changes to a value are being rejected—that's enforcing a format! My thought in this issue was that the demo should be showing the entries polished up, as they could be in the admin interface. I think we should be demoing the best capabilities of the project, not its shortcomings. Purposefully including data that's not formatted the way we display similar values serves what purpose?

I'm just trying to make the demo look the best I can. What do you suggest Ohana Web Search does with the vanity_number values?

[monfresh]

I understand your point of view, and your desire to format phone numbers consistently in OWS is totally valid. What I'm saying is that the formatting is a client concern, not an API concern. If you want parentheses around the first three digits of a vanity number, you should apply that on the client side because you can't assume that it will be formatted that way in the API response.

In addition, keep in mind that we probably don't want to hardcode a particular formatting because some OWS deployments might want to use a format without parentheses, like 703-555-1212.