Location ID Required for Services?

[devinbalkind]

Looking at the "Human Services Data Specification" Google Doc I see that the location ID is required for services, but as someone who manages services information in NYC, I can testify that a variety of services that don't have a specific location and instead are accessed by phone, and less frequently, the web.

Can the spec be changed so that locations are optional?

[monfresh]

Thanks for the feedback.

Please note that a Location does not necessarily have to be a physical address. It can also represent non-physical locations, such a website or a phone hotline which provides the Service. The documentation needs to be updated to reflect that.

This is very similar to the AIRS schema, which uses "Site" instead of "Location". Here is the description of a Site from the AIRS XSD:

Sites are physical locations or none physical locations (a website or hotline).
Site is used for two purposes. First it is used by Agency to provide the location 
of the agency Agency.AgencyLocation 
(Note this type of Site would never have any SiteService children).
Second sites are also the location where services are provided.
This would be the Agency.Site element
(Note this type of Site would have SiteService children.

This would mean that the Location/Site fields that are required would depend on whether the Location/Site is physical or non-physical. This is currently not the case in OpenReferral, which requires a Location to have at least one of either physical or mailing address, which is wrong and should be updated.

And here is the AIRS description of "SiteService" ("Service" in OpenReferral):

SiteService is the smallest unit describing a "service" that is offered at a Site.
It can be thought of as the intersection of a Site and a Taxonomy code 
(or related Taxonomy codes) and meta data about what is offered. 
A "Service" however is not represented as its own element because the "Service" 
cannot exist without a location (the site).

[devinbalkind]

I see. That's good. Sounds like the "serviceChannel" distinction from the W3C spec.

This brings me to a deeper architectural question: why use a location spec to describe something without a geographic location?

A little background about me: I'm currently designing a services data spec for Sahana EDEN, a resource management system for emergencies/disasters. This system, like many others I think, requires locations to have physical addresses. One of the reasons for this is the tight integration between locations (it calls them "facilities") and GIS/mapping functionality.

Facilities have their own contact info. They can also be associated with individuals that have their own contact info and are associated with organizations. Organizations have general contact info and can be associated with individual contacts as well.

I'm explaining all this because I want to suggest that maybe services should have their own, non-geographically attached phones and email addresses (just as they have URLs). It also looks to me like locations bind services to organizations. I think it would be useful for services to bind directly to organizations so that, unless the service has a physical location, it doesn't need to use the locations spec. Or is there an architectural reason for that not to be the case?

Thanks!

[spara]

There's no architectural reason, it's a legacy of the data set we used to build Ohana. I'm ok with Location having an optional physical or mailing address, but it would be misleading to call the entity Location. Maybe switch to Sites instead where it's mandatory to have a field called 'how_to_access' with an enumeration of physical, mailing, email, website, or phone.

What do y'all think?

[monfresh]

"Site" is a synonym of "location", so I'm not sure it makes that much of a difference. The English dictionary does not equate "location" with a geographic location.

If we were to add a "how_to_access" field, it would be an attribute of Service, not Site or Location. It's the Service that is accessed in one or more ways, not the Site. The purpose of that field would then be to determine which attributes would be required for the Service. For example, if it can be accessed by phone and physical location, then it must have a value for phone, as well as a Location entity.

Devin, is this the new structure you're proposing? Organization --> Services Organization --> Locations Service --> Locations

[spara]

In practice and from a colloquial English point of view, location usually refers to a place with a geographic location. I think we're splitting hairs and creating definitions without the benefit of a larger community discussion, so I would just rather not make it mandatory and provide keys to link either way. So more like this:

Organization --< Services Organization --< Locations Service >--< Locations

[devinbalkind]

I think I like Sophia's arrows. I'll repeat them as I understand them:

Services and locations have organizations and services and locations are related (optionally) to each other.

In our directory, we also have a number of location (facilities) that don't act as service channels - such as nonprofit-run warehouses of offices that don't provide services to the public. Managing this information might be out of the scope of this project but I do want to bring it up.

I think the term locations and sites are both geo-y. I liked how the old W3C spec used the term "serviceChannel" - or "channel".

I think the only required field for a location/channel should be it's organization. Often the service description and short_desc will be defined in the Service component so I don't think they shouldn't be required for the location component. Those should only be used it it's different from what's in the Service component.

As for "how_to_apply", I think:

• it should be an attribute of services
• it should be "how_to_access" because you don't always need to apply for services
• it should be an array of strings that are of the type "channel". There are numerous ways to access some services of numerous types. Ex. call with 800 number of visit one of our three offices.

My 2 cents. :)

PS: I think this project is massively important! Thanks so much.

On Fri, Mar 14, 2014 at 6:36 PM, Sophia Parafina notifications@github.comwrote:

In practice and from a colloquial English point of view, location usually refers to a place with a geographic location. I think we're splitting hairs and creating definitions without the benefit of a larger community discussion, so I would just rather not make it mandatory and provide keys to link either way. So more like this:

Organization --< Services Organization --< Locations Service >--< Locations

Reply to this email directly or view it on GitHubhttps://github.com/codeforamerica/OpenReferral/issues/28#issuecomment-37704608 .

Devin Balkind Founder & Director

Sarapis 134 Spring St, Suite 302 New York, NY, 1001 m.917.748.1048 devin@sarapis.org sarapis.org

[anselmbradford]

Here's an entity diagram:

One Organization can have multiple Locations and multiple Services. A single Location can provide multiple Services and a single Service can be at multiple Locations.

[spara]

Here's what I have at the moment. Not to different from Ans, except for a an additional join support table to n..n between service and location. It doesn't have to be implemented that way but it can be.

[anselmbradford]

Nice! Yeah, I was just illustrating what was written, I wasn't proposing a structure (for one thing, the singular table names in Sophia's diagram is better than plural!). ... I'm curious though, what's the additional join table for? Is that just so a query can semantically be one direction (location_has_service) or the other (service_has_location)? They look like identical tables other than the name.

[michaelwang1]

sweet yeah this is what i was getting at with my previous request...sorry i never had time to get back into it in detail. At a more phillosophical architechtural level, is there really a need for a seperate location table? In my experience, the contact info I'd typicall be look for, for example, fields location.emails, location.hours, locations.transportation are typically things I look for on a service-level search. I think in corner cases where service has multiple locations, its fine to list them as separate services. In my mind as a provider, if there are multiple locations with a higher level structure on top of it, that higher level should exist at the organization level. Vice versa, I'm not sure there is much reason for the "location" to require more than a common address to link together services with a common location. This would probably make the joining more efficient? -Michael (current background: md intern, semi-retired sql report writer, helping dennis with HHA, past advocate for healthleads and involved in their early resource database dev)

On Fri, Mar 14, 2014 at 4:54 PM, Ans notifications@github.com wrote:

Nice! Yeah, I was just illustrating what was written, I wasn't proposing a structure (for one thing, the singular table names in Sophia's diagram is better than plural!). ... I'm curious though, what's the additional join table for? Is that just so a query can semantically be one direction (location_has_service) or the other (service_has_location)? They look like identical tables other than the name.

Reply to this email directly or view it on GitHubhttps://github.com/codeforamerica/OpenReferral/issues/28#issuecomment-37708703 .

[anselmbradford]

Hi Michael, thanks for your interest in the project! I think having a separate location ties into database normalization to reduce database redundancy and increase flexibility. As you mention this could be in reality all edge cases, however, having a separate table future-proofs the database relations better, with the minimal overhead of an additional join. I think for small datasets this is okay, but @spara can fill in better than I can.

@spara, looking at the fields in your diagram closer, I wonder about the following:

1. coordinates seems like it needs to be in the address table, not the location table. Because if a location has the capabilities of having multiple addresses, the coordinates can't be set once for the location.
2. I'm confused why location has a description and short_desc? I'd agree with @michaelwang1 that a location could require at bare minimum a physical address (OR a phone OR an internet resource).
3. the languages field seems like it should be in the service table. What about a location that has multiple services in different languages that meet there? All the applicable languages could be picked out and listed at the location, but this doesn't tell which services are offered in which languages, which is the important data point.
4. Similar to the above I'm confused why hours is tied to the location and not the services. Services administered at a location could have vastly different hours. If the location lists the hours, how are a specific service's hours picked out?

I realize a lot of the above is a consequence of the legacy of our data and maybe I'm forgetting if those points have already been hashed out in earlier discussions.

EDIT: @spara figured it out on my own... (1) there are one-to-many for addresses b/c of physical & mailing address. (2) The location description and short description are the overall description and summary, while each service has a more specific description/summary. I'd tend to agree Site or Channel or Program may be a better name fit here to avoid the confusion with geographic location. (3) & (4) I'm still not clear on... seems like ideally the location should aggregate the hours & languages at Update on the service table.

[spara]

This is still a work in progress. Everyone's input is greatly appreciated. Stay tuned, I should have a more cleaned up version to push this week.

[monfresh]

Do we have a process by which changes get approved? For example, for this particular addition of a join table between services and location, how many votes would it take to make it official, and do we need a certain number of votes from people with a certain level of expertise? Is everyone who should have a say "watching" this repo and participating in the conversation?

[spara]

This is the revision that Jack talked about before releasing to the general community to review. It incorporates the comments from last fall. I think we need to form a working group that will review this and make the changes. In the standards committees that I have worked in, a general consensus was the process, with committee members raising and working issues until they felt they had a spec ready for review. After the review period ended and any changes/revisions were done, it was put to a vote for adoption by the general membership.

Note that all of this notional and up for revision. An organization can choose which joins make sense for them. The data model is designed to be generic enough to support their particular structure/schema.

[spara]

Ans,

I haven't pushed the markdown of the spec. There was a issue about languages regarding a distinction between languages spoken at location and services provided in non-English languages. For example, a location may have a Spanish speaking contact, but not a Spanish speaking doctor providing healthcare. That distinction is made in the spec. On one hand, I think it might be too nuanced for the generic model we're trying to create, but on the other, this is the kind of specificity that we would like to see. At the moment, I think I'll keep languages in both services and location with a footnote explaining the difference.

As for hours, I agree. In fact you are raising the same issue as the language issue. Good catch, I'll add hours with the footnote about the difference between the two,

[anselmbradford]

@spara Sophia, thanks for the explanation. With languages, that brings up whether a language field should be in the contact and service table, instead of the location table. The languages in location really are the aggregate_language of contact and service. As you say, that could be getting too nuanced though.

What about the extra join table? Is that easy to explain? I'm just curious to learn what that adds b/c I haven't seen that structure before.

[spara]

@anselmbradford I think I want to leave languages where they are now and let a working committee decide based on best practices;

The extra join tables are a product of SQLWorkbench when I added a many to many join between location and services. I might have to take them out an just draw in the join for a more traditional ER diagram. I think SQLWorkbench can be overly helpful.

[anselmbradford]

@spara, gotcha. Delete one of them and remove the location_organization_organization_id foreign key from the remaining table would keep your many-to-many relationship as far as I can see.

[monfresh]

I was thinking about this recently and I think there's a solution that would be more future-proof and flexible than changing the schema. What about having a virtual boolean field in the Locations table that identifies whether or not the Location has a physical address?

An app like Ohana API can then make use of that virtual field to determine whether or not to require an address. This came up for the SF team during NDoCH, and they ran into the validation issues because the API assumed that all locations must have an address. Having a field like virtual would be the easiest way to allow those locations to be entered into the DB.

[spara]

We could just remove the constraint that an organization has a physical address. In the model, an address can be physical, mailing, or other.

[devinbalkind]

Hi. Has this issue been resolved?

We're doing an import of services information, much of which doesn't have physical addresses, and it appears that the facilities field is required and it needs to be an address.

Thanks.

[spara]

In the specification, location is not required. However, I think Ohana API currently requires location, but I think constraint could be relaxed. Eventually, the specification and Ohana API will synch up, but I think that this is the current state.

[devinbalkind]

Oh I didn't realize the spec and Ohana were out of sync. That makes our work a bit more confusing. Any idea when they'll be sync up? Any chance we could get that constraint "relaxed" in the near future?

[spara]

It's a database constraint, so Moncef would be the best person to ask. I think he's traveling today to the CfA Summit , but he should get back to you soon about that.

[monfresh]

@devinbalkind Ohana is a work in progress and should not be considered production-ready until January 2015. Things can and will change frequently between now and then. Since Ohana existed before the spec, it did not make sense to update Ohana until the spec was somewhat stable. v0.2 was just released, and I will be reviewing it and making changes to Ohana to sync them, or proposing changes to the spec if necessary.

Having said that, if you have a pressing need to test importing data into your instance of the API, you can always make changes in your fork. To remove the address requirement, just comment out these lines: https://github.com/codeforamerica/ohana-api/blob/master/app/models/location.rb#L37-47

[devinbalkind]

Gotcha. Thanks for the info @monfresh